001: /*
002: *
003: *
004: * Copyright 1990-2007 Sun Microsystems, Inc. All Rights Reserved.
005: * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER
006: *
007: * This program is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU General Public License version
009: * 2 only, as published by the Free Software Foundation.
010: *
011: * This program is distributed in the hope that it will be useful, but
012: * WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * General Public License version 2 for more details (a copy is
015: * included at /legal/license.txt).
016: *
017: * You should have received a copy of the GNU General Public License
018: * version 2 along with this work; if not, write to the Free Software
019: * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
020: * 02110-1301 USA
021: *
022: * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
023: * Clara, CA 95054 or visit www.sun.com if you need additional
024: * information or have any questions.
025: */
026:
027: package com.sun.kvem.midp.pim;
028:
029: import javax.microedition.pim.PIMException;
030: import com.sun.midp.main.Configuration;
031: import java.util.Calendar;
032: import java.util.TimeZone;
033: import java.util.Date;
034:
035: /**
036: * Porting layer for PIM functionality. Implemented by PIMBridge
037: *
038: */
039: public abstract class PIMHandler {
040: /** Current handle for PIMHandler. */
041: private static PIMHandler instance;
042:
043: /**
044: * Gets a handle to the current PIMHandler.
045: * @return PIM handler
046: */
047: public static PIMHandler getInstance() {
048: if (instance == null) {
049: String className = Configuration
050: .getProperty("javax.microedition.pim.handler");
051: if (className == null) {
052: className = "com.sun.kvem.midp.pim.PIMBridge";
053: }
054: boolean isExcThrown = false;
055: try {
056: instance = (PIMHandler) Class.forName(className)
057: .newInstance();
058: } catch (ClassNotFoundException e) {
059: isExcThrown = true;
060: } catch (Error e) {
061: isExcThrown = true;
062: } catch (IllegalAccessException e) {
063: isExcThrown = true;
064: } catch (InstantiationException e) {
065: isExcThrown = true;
066: }
067: if (isExcThrown) {
068: throw new Error("PIM handler could not be initialized.");
069: }
070: }
071:
072: return instance;
073: }
074:
075: /**
076: * Gets all fields that are supported in this list. All fields supported by
077: * this list, including both standard and extended, are returned in this
078: * array.
079: *
080: * @param listHandle handle of list
081: * @return an int array containing all fields supported by this list. The
082: * order of the fields returned is unspecified. If there are no
083: * supported fields, a zero-length array is returned.
084: */
085: public abstract int[] getSupportedFields(Object listHandle);
086:
087: /**
088: * Checks if field is supported in list.
089: * @param listHandle handle of list
090: * @param field identifier of field
091: * @return <code>true</code> if field supported
092: */
093: public abstract boolean isSupportedField(Object listHandle,
094: int field);
095:
096: /**
097: * Checks if field has default value.
098: * @param listHandle handle of list
099: * @param field identifier of field
100: * @return <code>true</code> if field supported
101: */
102: public abstract boolean hasDefaultValue(Object listHandle, int field);
103:
104: /**
105: * Gets the data type of the field.
106: * @param listHandle handle of list
107: * @param field identifier of field
108: * @return data type identifier
109: */
110: public abstract int getFieldDataType(Object listHandle, int field);
111:
112: /**
113: * Gets the label of the field.
114: * @param listHandle handle of list
115: * @param field identifier of field
116: * @return label of the field
117: */
118: public abstract String getFieldLabel(Object listHandle, int field);
119:
120: /**
121: * Gets the default integer value for the given field. This will
122: * only
123: * return a valid value if hasDefaultValue(listType, field) returns true.
124: * @param listHandle handle of list
125: * @param field identifier of field
126: * @return default value of the field
127: */
128: public abstract int getDefaultIntValue(Object listHandle, int field);
129:
130: /**
131: * Gets the default string value for the given field. This will
132: * only
133: * return a valid value if hasDefaultValue(listType, field) returns true.
134: * @param listHandle handle of list
135: * @param field identifier of field
136: * @return default value of the field
137: */
138: public abstract String getDefaultStringValue(Object listHandle,
139: int field);
140:
141: /**
142: * Gets the default String[] value for the given field. This will
143: * only
144: * return a valid value if hasDefaultValue(listType, field) returns true.
145: * @param listHandle handle of list
146: * @param field identifier of field
147: * @return default value of the field
148: */
149: public abstract String[] getDefaultStringArrayValue(
150: Object listHandle, int field);
151:
152: /**
153: * Gets the default date value for the given field. This will only
154: * return a valid value if hasDefaultValue(listType, field) returns true.
155: * @param listHandle handle of list
156: * @param field identifier of field
157: * @return default value of the field
158: */
159: public abstract long getDefaultDateValue(Object listHandle,
160: int field);
161:
162: /**
163: * Gets the default byte[] value for the given field. This will
164: * only
165: * return a valid value if hasDefaultValue(listType, field) returns true.
166: * @param listHandle handle of list
167: * @param field identifier of field
168: * @return default value of the field
169: */
170: public abstract byte[] getDefaultBinaryValue(Object listHandle,
171: int field);
172:
173: /**
174: * Gets the default boolean value for the given field. This will
175: * only
176: * return a valid value if hasDefaultValue(listType, field) returns true.
177: * @param listHandle handle of list
178: * @param field identifier of field
179: * @return default value of the field
180: */
181: public abstract boolean getDefaultBooleanValue(Object listHandle,
182: int field);
183:
184: /**
185: * Gets the supported attributes for the given field.
186: * @param listHandle handle of list
187: * @param field identifier of field
188: * @return array of supported attributes of the field
189: */
190: public abstract int[] getSupportedAttributes(Object listHandle,
191: int field);
192:
193: /**
194: * Gets a mask containing all possible attributes for the given field.
195: *
196: * @param listHandle handle of list
197: * @param field the field number
198: * @return supported attribute mask
199: */
200: public abstract int getSupportedAttributesMask(Object listHandle,
201: int field);
202:
203: /**
204: * Gets attribute label for the given field attribute.
205: *
206: * @param listHandle handle of list
207: * @param attribute identifier of attribute
208: * @return attribute label
209: */
210: public abstract String getAttributeLabel(Object listHandle,
211: int attribute);
212:
213: /**
214: * Checks if attribute is supported.
215: *
216: * @param listHandle handle of list
217: * @param field the field number
218: * @param attribute identifier of attribute
219: * @return <code>true</code> if attribute is supported
220: */
221: public abstract boolean isSupportedAttribute(Object listHandle,
222: int field, int attribute);
223:
224: /**
225: * Checks if size of the string array.
226: *
227: * @param listHandle handle of list
228: * @param field the field number
229: * @return size of the string array
230: */
231: public abstract int getStringArraySize(Object listHandle, int field);
232:
233: /**
234: * Gets the array of supported elements.
235: *
236: * @param listHandle handle of list
237: * @param field the field number
238: * @return array of supported elements
239: */
240: public abstract int[] getSupportedArrayElements(Object listHandle,
241: int field);
242:
243: /**
244: * Gets the array element label.
245: *
246: * @param listHandle handle of list
247: * @param field the field number
248: * @param arrayElement the element identifier
249: * @return label fro the array element
250: */
251: public abstract String getArrayElementLabel(Object listHandle,
252: int field, int arrayElement);
253:
254: /**
255: * Checks if the array element is supported.
256: *
257: * @param listHandle handle of list
258: * @param field the field number
259: * @param arrayElement the element identifier
260: * @return <code>true</code> if attribute element is supported
261: */
262: public abstract boolean isSupportedArrayElement(Object listHandle,
263: int field, int arrayElement);
264:
265: /**
266: * Get the maximum number of values that can be stored in the given field.
267: *
268: * @param listHandle handle of list
269: * @param field the field type
270: * @return the maximum value
271: */
272: public abstract int getMaximumValues(Object listHandle, int field);
273:
274: /**
275: * Get the supported list names for the given list type. All list elements
276: * must be unique within the list.
277: *
278: * @param listType the type of the list
279: * @return a non-null array of supported list names. A copy of this array is
280: * returned by PIM.listPIMLists()
281: */
282: public abstract String[] getListNames(int listType);
283:
284: /**
285: * Get the name of the default list for the given type.
286: *
287: * @param listType the type of the list
288: * @return the name of the default list, or null if no list of this type
289: * is supported.
290: */
291: public abstract String getDefaultListName(int listType);
292:
293: /**
294: * Opens list.
295: *
296: * @param listType the type of the list
297: * @param listName the name of the list
298: * @param openMode open mode
299: * @return list handle that will be used to access this list
300: * @throws PIMException in case of I/O error.
301: */
302: public abstract Object openList(int listType, String listName,
303: int openMode) throws PIMException;
304:
305: /**
306: * Closes list.
307: *
308: * @param listHandle handle of list
309: * @throws PIMException in case of I/O error.
310: */
311: public abstract void closeList(Object listHandle)
312: throws PIMException;
313:
314: /**
315: * Get list element keys.
316: *
317: * @param listHandle handle of list
318: * @return an array of objects representing PIM element keys. These keys
319: * are to be passed to getListElement() and commitListElement().
320: * @throws PIMException in case of I/O error.
321: */
322: public abstract Object[] getListKeys(Object listHandle)
323: throws PIMException;
324:
325: /**
326: * Get the data for a list element.
327: * @param listHandle handle of list
328: * @param elementKey the key of the requested element
329: * @return a byte array containing the element data in a supported format
330: * @throws PIMException in case of I/O error.
331: */
332: public abstract byte[] getListElement(Object listHandle,
333: Object elementKey) throws PIMException;
334:
335: /**
336: * Get categories for the specified list element.
337: * @param listHandle handle of list
338: * @param elementKey the key of the requested element
339: * @return an array of categories names
340: * @throws PIMException in case of I/O error.
341: */
342: public abstract String[] getListElementCategories(
343: Object listHandle, Object elementKey) throws PIMException;
344:
345: /**
346: * Commit a list element.
347: *
348: * @param listHandle handle of the list
349: * @param elementKey the key of the element to be stored, or null if this
350: * is a new element.
351: * @param element element data in a form that can be interpreted
352: * by getListElement()
353: * @param categories list of categories which the list element belongs to
354: * @return a non-null key for this element, to be used in future calls
355: * to commitListElement() and getListElement()
356: * @throws PIMException in case of I/O error.
357: */
358: public abstract Object commitListElement(Object listHandle,
359: Object elementKey, byte[] element, String[] categories)
360: throws PIMException;
361:
362: /**
363: * Gets the set of categories defined for a list.
364: *
365: * @param listHandle handle of list
366: * @return the set of defined categories
367: * @throws PIMException If an error occurs or
368: * the list is no longer accessible or closed.
369: */
370: public abstract String[] getCategories(Object listHandle)
371: throws PIMException;
372:
373: /**
374: * Adds a category to the categories defined for a list.
375: *
376: * @param listHandle handle of list
377: * @param category category name
378: * @throws PIMException If an error occurs or
379: * the list is no longer accessible or closed.
380: * @see #getCategories
381: */
382: public abstract void addCategory(Object listHandle, String category)
383: throws PIMException;
384:
385: /**
386: * Deletes a category from the categories defined for a list.
387: *
388: * @param listHandle handle of list
389: * @param category category name
390: * @throws PIMException If an error occurs or
391: * the list is no longer accessible or closed.
392: * @see #getCategories
393: */
394: public abstract void deleteCategory(Object listHandle,
395: String category) throws PIMException;
396:
397: /**
398: * Rename a category.
399: *
400: * @param listHandle handle of list
401: * @param currentCategory current category name
402: * @param newCategory new category name
403: * @throws PIMException If an error occurs or
404: * the list is no longer accessible or closed.
405: * @see #getCategories
406: */
407: public abstract void renameCategory(Object listHandle,
408: String currentCategory, String newCategory)
409: throws PIMException;
410:
411: /** YEAR - constant from Calendar class. */
412: private final int YEAR = Calendar.YEAR;
413: /** MONTH - constant from Calendar class. */
414: private final int MONTH = Calendar.MONTH;
415: /** DAY_OF_MONTH - constant from Calendar class. */
416: private final int DAY_OF_MONTH = Calendar.DAY_OF_MONTH;
417: /** HOUR_OF_DAY - constant from Calendar class. */
418: private final int HOUR_OF_DAY = Calendar.HOUR_OF_DAY;
419: /** MINUTE - constant from Calendar class. */
420: private final int MINUTE = Calendar.MINUTE;
421: /** SECOND - constant from Calendar class. */
422: private final int SECOND = Calendar.SECOND;
423:
424: /**
425: * Adds the "0" prefix to one-digit number in string representation.
426: *
427: * @param str number in string representation
428: *
429: * @return two-digit number in string representation
430: */
431: private String prefix_0(String str) {
432: String returnValue = "";
433: if (str.length() < 2) { // x convert to 0x
434: returnValue = "0";
435: }
436: returnValue += str;
437: return returnValue;
438: }
439:
440: /**
441: * Converts date in format yyyy-MM-dd or yyyyMMdd to milliseconds.
442: *
443: * @param s date in format yyyy-MM-dd or yyyyMMdd
444: *
445: * @return number of milliseconds
446: */
447: public long parseDate(String s) {
448: Calendar local_calendar = Calendar.getInstance();
449:
450: // reset calendar to the state it is in composeDate method to get
451: // the same values for hours, minutes, seconds and milliseconds.
452: Date cldc_date = new Date(0);
453: local_calendar.setTime(cldc_date);
454:
455: int year, month, day;
456: if (s.indexOf('-') != -1) { // yyyy-MM-dd
457: year = Integer.parseInt(s.substring(0, 4));
458: month = Integer.parseInt(s.substring(5, 7));
459: day = Integer.parseInt(s.substring(8, 10));
460: } else { // yyyyMMdd
461: year = Integer.parseInt(s.substring(0, 4));
462: month = Integer.parseInt(s.substring(4, 6));
463: day = Integer.parseInt(s.substring(6, 8));
464: }
465:
466: local_calendar.set(Calendar.YEAR, year);
467: local_calendar.set(Calendar.MONTH, month - 1);
468: local_calendar.set(Calendar.DAY_OF_MONTH, day);
469:
470: return (local_calendar.getTime()).getTime();
471: }
472:
473: /**
474: * Converts date in milliseconds to yyyy-MM-dd string.
475: *
476: * @param date number of milliseconds
477: *
478: * @return date in format yyyy-MM-dd
479: */
480: public String composeDate(long date) { // yyyy-MM-dd
481: Calendar local_calendar = Calendar.getInstance();
482:
483: Date cldc_date = new Date(date);
484: local_calendar.setTime(cldc_date);
485:
486: String returnValue = Integer.toString(local_calendar.get(YEAR))
487: + "-"
488: + prefix_0(Integer
489: .toString(local_calendar.get(MONTH) + 1))
490: + "-"
491: + prefix_0(Integer.toString(local_calendar
492: .get(DAY_OF_MONTH)));
493:
494: return returnValue;
495: }
496:
497: /**
498: * Converts date in milliseconds to yyyymmdd string.
499: *
500: * @param date number of milliseconds
501: *
502: * @return date in format yyyymmdd
503: */
504: public String composeDate1(long date) { // yyyymmdd
505: Date cldc_date = new Date(date);
506: Calendar local_calendar = Calendar.getInstance();
507: local_calendar.setTime(cldc_date);
508:
509: String returnValue = Integer.toString(local_calendar.get(YEAR))
510: + prefix_0(Integer
511: .toString(local_calendar.get(MONTH) + 1))
512: + prefix_0(Integer.toString(local_calendar
513: .get(DAY_OF_MONTH)));
514:
515: return returnValue;
516: }
517:
518: /**
519: * Converts date/time in format yyyyMMddTHHmmss(Z) to milliseconds.
520: *
521: * @param s date/time in format yyyyMMddTHHmmss(Z)
522: *
523: * @return number of milliseconds
524: */
525: public long parseDateTime(String s) {
526: Calendar local_calendar;
527: if (s.length() > 15 && s.charAt(15) == 'Z') { // absolute time
528: local_calendar = Calendar.getInstance(TimeZone
529: .getTimeZone("GMT"));
530: } else {
531: local_calendar = Calendar.getInstance();
532: }
533: int year, month, day, hour, min, sec; // yyyyMMddTHHmmss
534: year = Integer.parseInt(s.substring(0, 4));
535: month = Integer.parseInt(s.substring(4, 6));
536: day = Integer.parseInt(s.substring(6, 8));
537: hour = Integer.parseInt(s.substring(9, 11));
538: min = Integer.parseInt(s.substring(11, 13));
539: sec = Integer.parseInt(s.substring(13, 15));
540:
541: local_calendar.set(Calendar.YEAR, year);
542: local_calendar.set(Calendar.MONTH, month - 1);
543: local_calendar.set(Calendar.DAY_OF_MONTH, day);
544: local_calendar.set(Calendar.HOUR_OF_DAY, hour);
545: local_calendar.set(Calendar.MINUTE, min);
546: local_calendar.set(Calendar.SECOND, sec);
547: local_calendar.set(Calendar.MILLISECOND, 0);
548:
549: return (local_calendar.getTime()).getTime();
550: }
551:
552: /**
553: * Converts date/time in milliseconds to yyyyMMddTHHmmss.
554: *
555: * @param date number of milliseconds
556: *
557: * @return date/time in format yyyyMMddTHHmmss
558: */
559: public String composeDateTime(long date) { // yyyyMMddTHHmmss
560: Date cldc_date = new Date(date);
561: Calendar local_calendar = Calendar.getInstance(TimeZone
562: .getTimeZone("GMT"));
563: local_calendar.setTime(cldc_date);
564: local_calendar.setTimeZone(TimeZone.getDefault());
565:
566: String returnValue = Integer.toString(local_calendar.get(YEAR))
567: + prefix_0(Integer
568: .toString(local_calendar.get(MONTH) + 1))
569: + prefix_0(Integer.toString(local_calendar
570: .get(DAY_OF_MONTH)))
571: + "T"
572: + prefix_0(Integer.toString(local_calendar
573: .get(HOUR_OF_DAY)))
574: + prefix_0(Integer.toString(local_calendar.get(MINUTE)))
575: + prefix_0(Integer.toString(local_calendar.get(SECOND)));
576:
577: return returnValue;
578: }
579: }
|