← Back to branch summary

~mortenoh/+junk/dhis2-detailed-import-export

« back to all changes in this revision

Viewing changes to dhis-2/dhis-api/src/main/java/org/hisp/dhis/period/PeriodService.java

  • Committer: larshelge at gmail
  • Date: 2009-03-03 16:46:36 UTC
  • Revision ID: larshelge@gmail.com-20090303164636-2sjlrquo7ib1gf7r
Initial check-in

Show diffs side-by-side

added added

removed removed

Lines of Context:
dhis-2/dhis-api/src/main/java/org/hisp/dhis/period/PeriodService.java
 
1
package org.hisp.dhis.period;
 
2
 
 
3
/*
 
4
 * Copyright (c) 2004-2007, University of Oslo
 
5
 * All rights reserved.
 
6
 *
 
7
 * Redistribution and use in source and binary forms, with or without
 
8
 * modification, are permitted provided that the following conditions are met:
 
9
 * * Redistributions of source code must retain the above copyright notice, this
 
10
 *   list of conditions and the following disclaimer.
 
11
 * * Redistributions in binary form must reproduce the above copyright notice,
 
12
 *   this list of conditions and the following disclaimer in the documentation
 
13
 *   and/or other materials provided with the distribution.
 
14
 * * Neither the name of the HISP project nor the names of its contributors may
 
15
 *   be used to endorse or promote products derived from this software without
 
16
 *   specific prior written permission.
 
17
 *
 
18
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
 
19
 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 
20
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 
21
 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
 
22
 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 
23
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 
24
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
 
25
 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 
26
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 
27
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
28
 */
 
29
 
 
30
import java.util.Collection;
 
31
import java.util.Date;
 
32
import java.util.List;
 
33
 
 
34
import org.hisp.dhis.dataelement.DataElement;
 
35
import org.hisp.dhis.source.Source;
 
36
 
 
37
/**
 
38
 * @author Kristian Nordal
 
39
 * @version $Id: PeriodService.java 5983 2008-10-17 17:42:44Z larshelg $
 
40
 */
 
41
public interface PeriodService
 
42
{
 
43
    String ID = PeriodService.class.getName();
 
44
 
 
45
    // -------------------------------------------------------------------------
 
46
    // Period
 
47
    // -------------------------------------------------------------------------
 
48
 
 
49
    /**
 
50
     * Adds a Period.
 
51
     * 
 
52
     * @param period the Period to add.
 
53
     * @return a generated unique id of the added Period.
 
54
     */
 
55
    int addPeriod( Period period );
 
56
 
 
57
    /**
 
58
     * Deletes a Period.
 
59
     * 
 
60
     * @param period the Period to delete.
 
61
     */
 
62
    void deletePeriod( Period period );
 
63
 
 
64
    /**
 
65
     * Returns a Period.
 
66
     * 
 
67
     * @param id the id of the Period to return.
 
68
     * @return the Period with the given id, or null if no match.
 
69
     */
 
70
    Period getPeriod( int id );
 
71
 
 
72
    /**
 
73
     * Returns a Period.
 
74
     * 
 
75
     * @param startDate the start date of the Period.
 
76
     * @param endDate the end date of the Period.
 
77
     * @param periodType the PeriodType of the Period
 
78
     * @return the Period matching the dates and periodtype, or null if no match.
 
79
     */
 
80
    Period getPeriod( Date startDate, Date endDate, PeriodType periodType );
 
81
    
 
82
    /**
 
83
     * Returns all persisted Periods.
 
84
     * 
 
85
     * @return all persisted Periods.
 
86
     */
 
87
    Collection<Period> getAllPeriods();
 
88
 
 
89
    /**
 
90
     * Returns all Periods with corresponding identifiers.
 
91
     * 
 
92
     * @param identifiers a collection of identifiers.
 
93
     * @return a collection of Periods.
 
94
     */
 
95
    Collection<Period> getPeriods( Collection<Integer> identifiers );
 
96
    
 
97
    /**
 
98
     * Returns all Periods with start date after or equal the specified start
 
99
     * date and end date before or equal the specified end date.
 
100
     * 
 
101
     * @param startDate the ultimate start date.
 
102
     * @param endDate the ultimate end date.
 
103
     * @return a collection of all Periods with start date after or equal the
 
104
     *         specified start date and end date before or equal the specified
 
105
     *         end date, or an empty collection if no Periods match.
 
106
     */
 
107
    Collection<Period> getPeriodsBetweenDates( Date startDate, Date endDate );
 
108
 
 
109
    /**
 
110
     * Returns all Periods of the specified PeriodType with start date after or 
 
111
     * equal the specified start date and end date before or equal the specified 
 
112
     * end date.
 
113
     * 
 
114
     * @param periodType the PeriodType.
 
115
     * @param startDate the ultimate start date.
 
116
     * @param endDate the ultimate end date.
 
117
     * @return a collection of all Periods with start date after or equal the
 
118
     *         specified start date and end date before or equal the specified
 
119
     *         end date, or an empty collection if no Periods match.
 
120
     */
 
121
    Collection<Period> getPeriodsBetweenDates( PeriodType periodType, Date startDate, Date endDate );
 
122
 
 
123
    /**
 
124
     * Returns all Intersecting Periods between the startDate and endDate based on PeriodType
 
125
     * For example if the startDate is 2007-05-01 and endDate is 2007-08-01 and periodType is Quartely
 
126
     * then it retuns the periods for Q2,Q3
 
127
     *  
 
128
     * @param periodType is the ultimate period type
 
129
     * @param startDate is intercepting startDate
 
130
     * @param endDate is intercepting endDate
 
131
     * @return
 
132
     */
 
133
    Collection<Period> getIntersectingPeriodsByPeriodType( PeriodType periodType, Date startDate, Date endDate );
 
134
 
 
135
    /**
 
136
     * Returns Periods where at least one its days are between the given start date and end date.
 
137
     * 
 
138
     * @param startDate the start date.
 
139
     * @param endDate the end date.
 
140
     * @return Periods where at least one its days are between the given start date and end date.
 
141
     */    
 
142
    Collection<Period> getIntersectingPeriods( Date startDate, Date endDate );
 
143
    
 
144
    /**
 
145
     * Returns all Periods from the given collection of Periods which span the border of either the
 
146
     * start date OR end date of the given Period. 
 
147
     * 
 
148
     * @param period the base Period.
 
149
     * @param periods the collection of Periods.
 
150
     * @return all Periods from the given collection of Periods which span the border of either the
 
151
     *         start date or end date of the given Period.
 
152
     */
 
153
    Collection<Period> getBoundaryPeriods( Period period, Collection<Period> periods );
 
154
 
 
155
    /**
 
156
     * Returns all Periods from the given collection of Periods which are completely within the
 
157
     * span of the of the given Period.
 
158
     * 
 
159
     * @param period the base Period.
 
160
     * @param periods the collection of Periods.
 
161
     * @return all Periods from the given collection of Periods which are completely within the
 
162
     *         span of the of the given Period.
 
163
     */
 
164
    Collection<Period> getInclusivePeriods( Period period, Collection<Period> periods );    
 
165
    
 
166
    /**
 
167
     * Returns all Periods with a given PeriodType.
 
168
     * 
 
169
     * @param periodType the PeriodType of the Periods to return.
 
170
     * @return all Periods with the given PeriodType, or an empty collection if
 
171
     *         no Periods match.
 
172
     */
 
173
    Collection<Period> getPeriodsByPeriodType( PeriodType periodType );
 
174
 
 
175
    /**
 
176
     * Returns all intersecting Periods for the given Period which have assosiated DataValues for
 
177
     * the given collection of DataElements and Sources.
 
178
     * 
 
179
     * @param period the Period.
 
180
     * @param dataElements the collection of DataElements.
 
181
     * @param sources the collection of Sources.
 
182
     * @return all intersecting Periods for the given Period which have assosiated DataValues for
 
183
     *         the given collection of DataElements and Sources.
 
184
     */
 
185
    Collection<Period> getPeriods( Period period, Collection<DataElement> dataElements, Collection<? extends Source> sources );
 
186
    
 
187
    /**
 
188
     * Returns a Period of type Relative. The Period will be persisted if it does
 
189
     * not exist.
 
190
     * 
 
191
     * @param date the date defining the base month for the Period generation.
 
192
     * @param startMonths the number of months of which to add to or subtract from the
 
193
     *        base month.
 
194
     * @param endMonths the number of months of which to add to or subtract from the
 
195
     *        base month.
 
196
     * @throws IllegalArgumentException if start months is equal to or greater than
 
197
     *         end months.
 
198
     * @return a Period of type Relative.
 
199
     */
 
200
    Period getRelativePeriod( Date date, int startMonths, int endMonths );
 
201
    
 
202
    /**
 
203
     * Returns a Period of type Relative. The Period will be persisted if it does
 
204
     * not exist.
 
205
     * 
 
206
     * @param date the date indicating in which month the start date will be. The
 
207
     *        start date is always the first day in the month. 
 
208
     * @param months the number of months the period will span. A positive value
 
209
     *        will return a period with current month's start date as start date
 
210
     *        and the month ( value - 1 ) months ahead in time's end date as end
 
211
     *        date. A negative value will return a period with current month's end
 
212
     *        date as end date and the month ( value - 1 ) months back in time's
 
213
     *        start date as start date.
 
214
     * @throws IllegalArgumentException if 0 is passed as second argument.
 
215
     * @return a Period of type Relative.
 
216
     */
 
217
    Period getRelativePeriod( Date date, int months );
 
218
 
 
219
    // -------------------------------------------------------------------------
 
220
    // PeriodType
 
221
    // -------------------------------------------------------------------------
 
222
 
 
223
    /**
 
224
     * Returns a PeriodType.
 
225
     * 
 
226
     * @param id the id of the PeriodType to return.
 
227
     * @return the PeriodType with the given id, or null if no match.
 
228
     */
 
229
    PeriodType getPeriodType( int id );
 
230
 
 
231
    /**
 
232
     * Returns all PeriodTypes.
 
233
     * 
 
234
     * @return a list of all PeriodTypes, or an empty list if there are no
 
235
     *         PeriodTypes. The PeriodTypes have a natural order.
 
236
     */
 
237
    List<PeriodType> getAllPeriodTypes();
 
238
 
 
239
    /**
 
240
     * Returns a PeriodType with a given name.
 
241
     * 
 
242
     * @param name the name of the PeriodType to return.
 
243
     * @return the PeriodType with the given name, or null if no match.
 
244
     */
 
245
    PeriodType getPeriodTypeByName( String name );
 
246
}