/protocols/smpp/src/main/java/org/mobicents/protocols/smpp/util/SMPPDate.java

  1/*
  2 * JBoss, Home of Professional Open Source
  3 * Copyright 2011, Red Hat, Inc. and individual contributors
  4 * by the @authors tag. See the copyright.txt in the distribution for a
  5 * full listing of individual contributors.
  6 *
  7 * This is free software; you can redistribute it and/or modify it
  8 * under the terms of the GNU Lesser General Public License as
  9 * published by the Free Software Foundation; either version 2.1 of
 10 * the License, or (at your option) any later version.
 11 *
 12 * This software is distributed in the hope that it will be useful,
 13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
 15 * Lesser General Public License for more details.
 16 *
 17 * You should have received a copy of the GNU Lesser General Public
 18 * License along with this software; if not, write to the Free
 19 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
 20 * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
 21 */
 22
 23package org.mobicents.protocols.smpp.util;
 24
 25import java.util.Calendar;
 26import java.util.TimeZone;
 27
 28/**
 29 * Object to represent an SMPP time specification.
 30 * There are two types of SMPP time specs: an absolute time and a relative
 31 * time. Absolute times specify the exact year, month, day, hour, minute,
 32 * second, tenths of a second and timezone. Relative times specify an
 33 * offset of years, months, days, hours, minutes and seconds from the
 34 * current time. Both types of time formats take the same string form
 35 * "YYMMDDhhmmss[tnnp]", where
 36 * <ul>
 37 * <li>YY is the representation of year, 00-99. The specification does not
 38 * define how these numbers are converted into actual years for absolute times.
 39 * By default, this API simply adds 2000 to this number to get the year.
 40 * This can be altered via the {@link SMPPDateFormat} class.</li>
 41 * <li>MM is the month (01-12).</li>
 42 * <li>DD is the day of the month (01-31)</li>
 43 * <li>hh is the hour (00-23)</li>
 44 * <li>mm is the minute (00-59)</li>
 45 * <li>ss is the second (00-59)</li>
 46 * <li>t is tenths of second (0-9)</li>
 47 * <li>nn is the time difference in quarter hours from UTC</li>
 48 * <li>p is one of '+', '-' or 'R'. + indicates the time is ahead of UTC, -
 49 * indicates it is behind UTC and R indicates the time specification is relative
 50 * to current SMSC time.</li>
 51 * </ul>
 52 * <p>
 53 * See section 7.1 of the SMPP v3.4 specification for the official definition
 54 * of SMPP time formats.
 55 * </p>
 56 * @see SMPPDateFormat
 57 * @version $Id: SMPPDate.java 463 2009-06-16 12:07:19Z orank $
 58 */
 59public abstract class SMPPDate implements java.io.Serializable {
 60    private static final long serialVersionUID = 3L;
 61
 62    protected SMPPDate() {
 63    }
 64
 65    /**
 66     * Get a date object representing an absolute time, as represented by
 67     * the supplied <code>calendar</code>. This is the same as calling
 68     * <code>SMPPDate.getAbsoluteInstance(calendar, true);</code>.
 69     * @param calendar A <code>java.util.Calendar</code> instance representing
 70     * the desired date, time and timezone for the SMPP time.
 71     * @return An SMPPDate object representing the date, time and timezone
 72     * specified by <code>calendar</code>.
 73     */
 74    public static SMPPDate getAbsoluteInstance(Calendar calendar) {
 75        return new AbsoluteSMPPDate(calendar);
 76    }
 77    
 78    /**
 79     * Get a date object representing an absolute time, as represented by
 80     * the supplied <code>calendar</code>. The returned object will either
 81     * use or ignore the timezone information in the calendar object,
 82     * depending on whether <code>withTz</code> is <code>true</code> or
 83     * <code>false</code>.
 84     * @param calendar A <code>java.util.Calendar</code> instance representing
 85     * the desired date, time and timezone for the SMPP time.
 86     * @param withTz <code>true</code> to return an object that uses the
 87     * timezone information specified in the calendar object, <code>false</code>
 88     * to return an SMPPDate that does not contain any timezone information.
 89     * @return An SMPPDate object representing the date, time and, optionally,
 90     * timezone specified by <code>calendar</code>.
 91     */
 92    public static SMPPDate getAbsoluteInstance(Calendar calendar, boolean withTz) {
 93        return new AbsoluteSMPPDate(calendar, withTz);
 94    }
 95    
 96    /**
 97     * Get a date object representing a relative time.
 98     * @param years The number of years.
 99     * @param months The number of months.
100     * @param days The number of days.
101     * @param hours The number of hours.
102     * @param minutes The number of minutes.
103     * @param seconds The number of seconds.
104     * @return An SMPPDate object representing the relative time specified
105     * by the supplied parameters.
106     */
107    public static SMPPDate getRelativeInstance(int years,
108            int months,
109            int days,
110            int hours,
111            int minutes,
112            int seconds) {
113        return new RelativeSMPPDate(years, months, days, hours, minutes, seconds);
114    }
115
116    /**
117     * Get a calendar object that represents the time specified by this
118     * SMPPDate. The returned value will be <code>null</code> for relative
119     * SMPP times. Also, for absolute SMPP times that do not contain timezone
120     * information, the returned calendar&apos;s timezone cannot be trusted -
121     * it will simply be initialised to whatever <code>java.util.Calendar</code>
122     * considers its default (usually the timezone of the JVM). 
123     * @return A calendar object, or <code>null</code> if this is a
124     * relative time specification.
125     */
126    public Calendar getCalendar() {
127        return null;
128    }
129    
130    /**
131     * Get the year part of this time format. The return value from this will
132     * be in the range 0 - 99 for relative times, or will be the full year
133     * (such as <code>2007</code>) for absolute times.
134     * @return The year part of this time format.
135     */
136    public abstract int getYear();
137    
138    /**
139     * Get the month part of this time format. This will always return a value
140     * in the range 1 - 12.
141     * @return The month part of this time format.
142     */
143    public abstract int getMonth();
144    
145    /**
146     * Get the day part of this time format. This will always return a value
147     * in the range 1 - 31.
148     * @return The day part of this time format.
149     */
150    public abstract int getDay();
151    
152    /**
153     * Get the hour part of this time format. This will always return a value
154     * in the range 0 - 23.
155     * @return The hour part of this time format.
156     */
157    public abstract int getHour();
158
159    /**
160     * Get the minute part of this time format. This will always return a value
161     * in the range 0 - 59.
162     * @return The minute part of this time format.
163     */
164    public abstract int getMinute();
165
166    /**
167     * Get the second part of this time format. This will always return a value
168     * in the range 0 - 59.
169     * @return The second part of this time format.
170     */
171    public abstract int getSecond();
172
173    /**
174     * Get the tenths of a second part of this time format. This will always
175     * return a value in the range 0 - 9.
176     * @return The tenths of a second part of this time format.
177     */
178    public int getTenth() {
179        return 0;
180    }
181    
182    /**
183     * Get the UTC offset part of this time format. This will always return a
184     * value in the range 0 - 48. The "direction" of the offset should
185     * be determined using {@link #getSign()}.
186     * @return The UTC offset part of this time format.
187     * @see #getTimeZone()
188     */
189    public int getUtcOffset() {
190        return 0;
191    }
192    
193    /**
194     * Get the timezone of this SMPPDate.
195     * @return The timezone of this SMPPDate object, or <code>null</code> if
196     * there is no timezone.
197     */
198    public TimeZone getTimeZone() {
199        return null;
200    }
201    
202    /**
203     * Get the timezone offset modifier character. For absolute time formats,
204     * this will return one of '+' if the timezone offset is ahead of UTC,
205     * '-' if the timezone offset is behind UTC, or <code>(char) 0</code> if
206     * there is no timezone information.
207     * @return One of '+', '-' or <code>(char) 0</code>.
208     */
209    public char getSign() {
210        return (char) 0;
211    }
212    
213    /**
214     * Determine if this date object represents an absolute time.
215     * @return <code>true</code> if this object is an absolute time,
216     * <code>false</code> otherwise.
217     */
218    public boolean isAbsolute() {
219        return false;
220    }
221    
222    /**
223     * Determine if this date object represents a relative time.
224     * @return <code>true</code> if this object is a relative time,
225     * <code>false</code> otherwise.
226     */
227    public boolean isRelative() {
228        return false;
229    }
230    
231    /**
232     * Determine if this date object has timezone information associated
233     * with it.
234     * @return <code>true</code> if this date object "knows" its timezone,
235     * <code>false</code> if it does not.
236     */
237    public boolean hasTimezone() {
238        return false;
239    }
240
241    /**
242     * Return the length this SMPP date would encode as.
243     * @return The number of bytes this SMPP date encodes to on the wire.
244     */
245    public int getLength() {
246        return 0;
247    }
248}