Subversion Repositories XServices

Rev

Rev 71 | Go to most recent revision | Only display areas with differences | Regard whitespace | Details | Blame | Last modification | View Log | RSS feed

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