Subversion Repositories XServices

Rev

Details | Last modification | View Log | RSS feed

Rev Author Line No. Line
66 brianR 1
/*
2
 *   Copyright 2011 Brian Rosenberger (Brutex Network)
3
 *
4
 *   Licensed under the Apache License, Version 2.0 (the "License");
5
 *   you may not use this file except in compliance with the License.
6
 *   You may obtain a copy of the License at
7
 *
8
 *       http://www.apache.org/licenses/LICENSE-2.0
9
 *
10
 *   Unless required by applicable law or agreed to in writing, software
11
 *   distributed under the License is distributed on an "AS IS" BASIS,
12
 *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13
 *   See the License for the specific language governing permissions and
14
 *   limitations under the License.
15
 */
16
 
17
package net.brutex.xservices.ws;
18
 
19
import java.math.BigInteger;
83 brianR 20
import java.util.Date;
66 brianR 21
import java.util.GregorianCalendar;
83 brianR 22
import java.util.List;
66 brianR 23
 
24
import javax.jws.WebMethod;
25
import javax.jws.WebParam;
26
import javax.jws.WebService;
27
import javax.xml.bind.annotation.XmlElement;
83 brianR 28
import javax.xml.datatype.XMLGregorianCalendar;
66 brianR 29
 
30
import net.brutex.xservices.types.DateFormatType;
83 brianR 31
import net.brutex.xservices.types.DateInfoExtendedType;
32
import net.brutex.xservices.types.DateInfoType;
66 brianR 33
import net.brutex.xservices.types.DateTimeUnits;
83 brianR 34
import net.brutex.xservices.types.TimeZoneType;
66 brianR 35
import net.brutex.xservices.util.BrutexNamespaces;
36
 
83 brianR 37
 
66 brianR 38
import org.apache.cxf.annotations.WSDLDocumentation;
39
import org.apache.cxf.annotations.WSDLDocumentationCollection;
40
 
41
/**
42
 * Date and time related services.
43
 * @author Brian Rosenberger
44
 *
45
 */
46
@WebService(targetNamespace = BrutexNamespaces.WS_XSERVICES)
47
@WSDLDocumentationCollection(
48
    {
49
    	@WSDLDocumentation(value = BrutexNamespaces.BRUTEX_COPYRIGHT, placement = WSDLDocumentation.Placement.TOP)
50
    }
51
)
52
public interface DateService {
53
 
54
	public static final String SERVICE_NAME = "DateService";
83 brianR 55
 
69 brianR 56
	final String OPERATION_GETDATE = "getDate";
83 brianR 57
	final String OPERATION_GETDATEEXTENDED = "getDateExtended";
69 brianR 58
	final String OPERATION_GETTIMESTAMP = "getTimestamp";
71 brianR 59
	final String OPERATION_GETTIMESTAMP2 = "getTimestamp2";
69 brianR 60
	final String OPERATION_GETINTIMEZONE = "getInTimezone";
61
	final String OPERATION_FORMATDATE = "formatDate";
62
	final String OPERATION_FORMATDATEADVANCED = "formatDateAdvanced";
63
	final String OPERATION_PARSEDATE = "parseDate";
64
	final String OPERATION_PARSEDATEADVANCED = "parseDateAdvanced";
65
	final String OPERATION_DATETIMEDIFF = "dateTimeDiff";
66
	final String OPERATION_DATETIMEDIFF2 = "dateTimeDiff2";
67
	final String OPERATION_DATEADD = "dateAdd";
83 brianR 68
	final String OPERATION_GETTIMEZONES = "getTimezones";
69 brianR 69
	final String PARAM_TIMEZONE = "timezone";
70
	final String PARAM_DATETIME = "datetime";
71
	final String PARAM_FORMAT = "format";
72
	final String PARAM_UNIT = "unit";
66 brianR 73
 
74
	/**
75
	 * Get current date and time.
76
	 *
77
	 * @return Current date and time.
78
	 * @throws XServicesFault
79
	 */
80
	@WebMethod(operationName=OPERATION_GETDATE)
81
	@WSDLDocumentation(value="Get current date and time.")
83 brianR 82
	public abstract DateInfoType getDate()
83
			throws XServicesFault;
66 brianR 84
 
85
	/**
83 brianR 86
	 * Get current date and time (extended version).
87
	 *
88
	 * @return Current date and time.
89
	 * @throws XServicesFault
90
	 */
91
	@WebMethod(operationName=OPERATION_GETDATEEXTENDED)
92
	@WSDLDocumentation(value="Get current date and time in different formats.")
93
	public abstract DateInfoExtendedType getDateExtended()
94
			throws XServicesFault;
95
 
96
	/**
66 brianR 97
	 * Get milliseconds since 01.01.1970.
98
	 *
99
	 * @return timestamp milliseconds
100
	 */
101
	@WebMethod(operationName=OPERATION_GETTIMESTAMP)
102
	@WSDLDocumentation(value="Get milliseconds since 01.01.1970 (Unix timestap).")
103
	public abstract BigInteger getTimestamp();
71 brianR 104
 
105
	/**
106
	 * Get seconds since 01.01.1970.
107
	 *
108
	 * @return timestamp seconds
109
	 */
110
	@WebMethod(operationName=OPERATION_GETTIMESTAMP2)
111
	@WSDLDocumentation(value="Get seconds since 01.01.1970 (Unix timestap).")
112
	public abstract BigInteger getTimestamp2();
66 brianR 113
 
114
	/**
115
	 * Display a date time with a different time zone.
116
	 * Changes representation only (no conversion).
117
	 *
118
	 * @param cal date time.
119
	 * @param timezone time zone
120
	 * @return date time
121
	 * @throws XServicesFault
122
	 */
123
	@WebMethod(operationName=OPERATION_GETINTIMEZONE)
83 brianR 124
	public abstract String getInTimezone(
125
			@WebParam(name=PARAM_DATETIME) @XmlElement(required=true) Date cal,
66 brianR 126
			@WebParam(name=PARAM_TIMEZONE) @XmlElement(required=true) String timezone) throws XServicesFault;
127
 
128
	/**
69 brianR 129
	 * Formats a date with pre-defined patterns.
130
	 *
83 brianR 131
	 * @param cal date time to be formatted in ISO8601
69 brianR 132
	 * @param format Pattern to be used for date formating
66 brianR 133
	 * @return formatted date/time string
134
	 * @throws XServicesFault
135
	 */
136
	@WebMethod(operationName=OPERATION_FORMATDATE)
137
	public abstract String formatDate(
83 brianR 138
			@WebParam(name=PARAM_DATETIME) @XmlElement(required=true) Date cal,
66 brianR 139
			@WebParam(name=PARAM_FORMAT) @XmlElement(required=true) DateFormatType format) throws XServicesFault;
140
 
83 brianR 141
	@WebMethod(operationName=OPERATION_GETTIMEZONES)
142
	public abstract List<TimeZoneType> getTimezones() throws XServicesFault;
143
 
69 brianR 144
	/**
145
	 * Formats a date with a free form pattern.
146
	 * Uses SimpleDateFormat patterns
147
	 * The following pattern letters are defined (all other characters from 'A' to 'Z' and from 'a' to 'z' are reserved):
148
 
149
    Letter	Date or Time Component	Presentation	Examples
150
    G	Era designator	Text	AD
151
    y	Year	Year	1996; 96
152
    M	Month in year	Month	July; Jul; 07
153
    w	Week in year	Number	27
154
    W	Week in month	Number	2
155
    D	Day in year	Number	189
156
    d	Day in month	Number	10
157
    F	Day of week in month	Number	2
158
    E	Day in week	Text	Tuesday; Tue
159
    a	Am/pm marker	Text	PM
160
    H	Hour in day (0-23)	Number	0
161
    k	Hour in day (1-24)	Number	24
162
    K	Hour in am/pm (0-11)	Number	0
163
    h	Hour in am/pm (1-12)	Number	12
164
    m	Minute in hour	Number	30
165
    s	Second in minute	Number	55
166
    S	Millisecond	Number	978
167
    z	Time zone	General time zone	Pacific Standard Time; PST; GMT-08:00
168
    Z	Time zone	RFC 822 time zone	-0800
169
	 * @param cal Date time to be formatted
170
	 * @param format Format string
171
	 * @return Date time formatted according to format string
172
	 * @throws XServicesFault
173
	 */
66 brianR 174
	@WebMethod(operationName=OPERATION_FORMATDATEADVANCED)
175
	public abstract String formatDateAdvanced(
83 brianR 176
			@WebParam(name=PARAM_DATETIME) @XmlElement(required=true) Date cal,
66 brianR 177
			@WebParam(name=PARAM_FORMAT) @XmlElement(required=true) String format) throws XServicesFault;
178
 
70 brianR 179
	/**
180
	 * Converts a string into date using pre-defined date formats.
181
	 *
182
	 * @param s Date/ time as string
183
	 * @param format date format
184
	 * @param timezone timezone
185
	 * @return XML Date
186
	 * @throws XServicesFault
187
	 */
66 brianR 188
	@WebMethod(operationName=OPERATION_PARSEDATE)
83 brianR 189
	@WSDLDocumentation(value="Converts a string into date using pre-defined date formats.")
190
	public abstract Date parseDate(
66 brianR 191
			@WebParam(name=PARAM_DATETIME) @XmlElement(required=true) String s,
192
			@WebParam(name=PARAM_FORMAT) @XmlElement(required=true) DateFormatType format,
193
			@WebParam(name=PARAM_TIMEZONE) String timezone) throws XServicesFault;
194
 
70 brianR 195
	/**
196
	 * Converts a string into date using any format.
197
	 * @param s date/ time as string
198
	 * @param format date format
199
	 * @param timezone timezone
200
	 * @return XML Date
201
	 * @throws XServicesFault
202
	 */
66 brianR 203
	@WebMethod(operationName=OPERATION_PARSEDATEADVANCED)
204
	public abstract GregorianCalendar parseDateAdvanced(
205
			@WebParam(name=PARAM_DATETIME) @XmlElement(required=true) String s,
206
			@WebParam(name=PARAM_FORMAT) @XmlElement(required=true) String format,
207
			@WebParam(name=PARAM_TIMEZONE) String timezone) throws XServicesFault;
208
 
69 brianR 209
	/**
210
	 * Calculate elapsed time between two dates.
211
	 * @param fromCal First date.
212
	 * @param toCal Second date.
213
	 * @return Elapsed time in milliseconds
214
	 * @throws XServicesFault
215
	 */
66 brianR 216
	@WebMethod(operationName=OPERATION_DATETIMEDIFF)
217
	public abstract BigInteger dateTimeDiff(
83 brianR 218
			@WebParam(name="fromDateTime") @XmlElement(required=true) Date fromCal,
219
			@WebParam(name="toDateTime") @XmlElement(required=true) Date toCal) throws XServicesFault;
66 brianR 220
 
221
	/**
222
	 * Fully elapsed units between two dates.
223
	 * 4:15:10-4:15:55 in minutes = 0 and in seconds = 45
224
	 *
225
	 * @param fromCal
226
	 * @param toCal
227
	 * @param unit
228
	 * @return Date/time difference in unit
229
	 * @throws XServicesFault
230
	 */
231
	@WebMethod(operationName=OPERATION_DATETIMEDIFF2)
232
	@WSDLDocumentation(value="Get elapsed time between to dates.")
233
	public abstract BigInteger dateTimeDiff2(
83 brianR 234
			@WebParam(name="fromDateTime") @XmlElement(required=true) Date fromCal,
235
			@WebParam(name="toDateTime") @XmlElement(required=true) Date toCal,
236
			@WebParam(name=PARAM_UNIT) DateTimeUnits unit) throws XServicesFault;
68 brianR 237
 
238
	/**
69 brianR 239
	 * Add or subtract a time span from a date.
68 brianR 240
	 *
69 brianR 241
	 * @param cal The initial date.
242
	 * @param value The amount to add.
243
	 * @param unit The unit the amount is defined in.
68 brianR 244
	 * @return New date and time.
245
	 * @throws XServicesFault
69 brianR 246
	 *
68 brianR 247
	 */
248
	@WebMethod(operationName=OPERATION_DATEADD)
249
	@WSDLDocumentation(value="Add or substract a time span from a date.")
250
	public abstract GregorianCalendar dateAdd(
251
			@WebParam(name=PARAM_DATETIME) @XmlElement(required=true) GregorianCalendar cal,
252
			@WebParam(name="value") @XmlElement(required=true) BigInteger value,
253
			@WebParam(name=PARAM_UNIT) @XmlElement(required=true) DateTimeUnits unit) throws XServicesFault;
254
 
66 brianR 255
}