FileDocCategorySizeDatePackage
PIMHandler.javaAPI DocphoneME MR2 API (J2ME)19668Wed May 02 18:00:28 BST 2007com.sun.kvem.midp.pim

PIMHandler

public abstract class PIMHandler extends Object
Porting layer for PIM functionality. Implemented by PIMBridge

Fields Summary
private static PIMHandler
instance
Current handle for PIMHandler.
private final int
YEAR
YEAR - constant from Calendar class.
private final int
MONTH
MONTH - constant from Calendar class.
private final int
DAY_OF_MONTH
DAY_OF_MONTH - constant from Calendar class.
private final int
HOUR_OF_DAY
HOUR_OF_DAY - constant from Calendar class.
private final int
MINUTE
MINUTE - constant from Calendar class.
private final int
SECOND
SECOND - constant from Calendar class.
Constructors Summary
Methods Summary
public abstract voidaddCategory(java.lang.Object listHandle, java.lang.String category)
Adds a category to the categories defined for a list.

param
listHandle handle of list
param
category category name
throws
PIMException If an error occurs or the list is no longer accessible or closed.
see
#getCategories

public abstract voidcloseList(java.lang.Object listHandle)
Closes list.

param
listHandle handle of list
throws
PIMException in case of I/O error.

public abstract java.lang.ObjectcommitListElement(java.lang.Object listHandle, java.lang.Object elementKey, byte[] element, java.lang.String[] categories)
Commit a list element.

param
listHandle handle of the list
param
elementKey the key of the element to be stored, or null if this is a new element.
param
element element data in a form that can be interpreted by getListElement()
param
categories list of categories which the list element belongs to
return
a non-null key for this element, to be used in future calls to commitListElement() and getListElement()
throws
PIMException in case of I/O error.

public java.lang.StringcomposeDate(long date)
Converts date in milliseconds to yyyy-MM-dd string.

param
date number of milliseconds
return
date in format yyyy-MM-dd

 // yyyy-MM-dd
        Calendar local_calendar =
            Calendar.getInstance();

        Date cldc_date = new Date(date);
        local_calendar.setTime(cldc_date);

        String returnValue = Integer.toString(local_calendar.get(YEAR)) +
            "-" + prefix_0(Integer.toString(local_calendar.get(MONTH)+1)) +
            "-" + prefix_0(Integer.toString(local_calendar.get(DAY_OF_MONTH)));

        return returnValue;
    
public java.lang.StringcomposeDate1(long date)
Converts date in milliseconds to yyyymmdd string.

param
date number of milliseconds
return
date in format yyyymmdd

 // yyyymmdd
        Date cldc_date = new Date(date);
        Calendar local_calendar =
            Calendar.getInstance();
        local_calendar.setTime(cldc_date);

        String returnValue = Integer.toString(local_calendar.get(YEAR)) +
            prefix_0(Integer.toString(local_calendar.get(MONTH)+1)) +
            prefix_0(Integer.toString(local_calendar.get(DAY_OF_MONTH)));

        return returnValue;
    
public java.lang.StringcomposeDateTime(long date)
Converts date/time in milliseconds to yyyyMMddTHHmmss.

param
date number of milliseconds
return
date/time in format yyyyMMddTHHmmss

 // yyyyMMddTHHmmss
        Date cldc_date = new Date(date);
        Calendar local_calendar =
            Calendar.getInstance(TimeZone.getTimeZone("GMT"));
        local_calendar.setTime(cldc_date);
        local_calendar.setTimeZone(TimeZone.getDefault());

        String returnValue = Integer.toString(local_calendar.get(YEAR)) +
            prefix_0(Integer.toString(local_calendar.get(MONTH)+1)) +
            prefix_0(Integer.toString(local_calendar.get(DAY_OF_MONTH)))
            + "T" +
            prefix_0(Integer.toString(local_calendar.get(HOUR_OF_DAY))) +
            prefix_0(Integer.toString(local_calendar.get(MINUTE))) +
            prefix_0(Integer.toString(local_calendar.get(SECOND)));

        return returnValue;
    
public abstract voiddeleteCategory(java.lang.Object listHandle, java.lang.String category)
Deletes a category from the categories defined for a list.

param
listHandle handle of list
param
category category name
throws
PIMException If an error occurs or the list is no longer accessible or closed.
see
#getCategories

public abstract java.lang.StringgetArrayElementLabel(java.lang.Object listHandle, int field, int arrayElement)
Gets the array element label.

param
listHandle handle of list
param
field the field number
param
arrayElement the element identifier
return
label fro the array element

public abstract java.lang.StringgetAttributeLabel(java.lang.Object listHandle, int attribute)
Gets attribute label for the given field attribute.

param
listHandle handle of list
param
attribute identifier of attribute
return
attribute label

public abstract java.lang.String[]getCategories(java.lang.Object listHandle)
Gets the set of categories defined for a list.

param
listHandle handle of list
return
the set of defined categories
throws
PIMException If an error occurs or the list is no longer accessible or closed.

public abstract byte[]getDefaultBinaryValue(java.lang.Object listHandle, int field)
Gets the default byte[] value for the given field. This will only return a valid value if hasDefaultValue(listType, field) returns true.

param
listHandle handle of list
param
field identifier of field
return
default value of the field

public abstract booleangetDefaultBooleanValue(java.lang.Object listHandle, int field)
Gets the default boolean value for the given field. This will only return a valid value if hasDefaultValue(listType, field) returns true.

param
listHandle handle of list
param
field identifier of field
return
default value of the field

public abstract longgetDefaultDateValue(java.lang.Object listHandle, int field)
Gets the default date value for the given field. This will only return a valid value if hasDefaultValue(listType, field) returns true.

param
listHandle handle of list
param
field identifier of field
return
default value of the field

public abstract intgetDefaultIntValue(java.lang.Object listHandle, int field)
Gets the default integer value for the given field. This will only return a valid value if hasDefaultValue(listType, field) returns true.

param
listHandle handle of list
param
field identifier of field
return
default value of the field

public abstract java.lang.StringgetDefaultListName(int listType)
Get the name of the default list for the given type.

param
listType the type of the list
return
the name of the default list, or null if no list of this type is supported.

public abstract java.lang.String[]getDefaultStringArrayValue(java.lang.Object listHandle, int field)
Gets the default String[] value for the given field. This will only return a valid value if hasDefaultValue(listType, field) returns true.

param
listHandle handle of list
param
field identifier of field
return
default value of the field

public abstract java.lang.StringgetDefaultStringValue(java.lang.Object listHandle, int field)
Gets the default string value for the given field. This will only return a valid value if hasDefaultValue(listType, field) returns true.

param
listHandle handle of list
param
field identifier of field
return
default value of the field

public abstract intgetFieldDataType(java.lang.Object listHandle, int field)
Gets the data type of the field.

param
listHandle handle of list
param
field identifier of field
return
data type identifier

public abstract java.lang.StringgetFieldLabel(java.lang.Object listHandle, int field)
Gets the label of the field.

param
listHandle handle of list
param
field identifier of field
return
label of the field

public static com.sun.kvem.midp.pim.PIMHandlergetInstance()
Gets a handle to the current PIMHandler.

return
PIM handler

        if (instance == null) {
            String className = Configuration
		.getProperty("javax.microedition.pim.handler");
            if (className == null) {
                className = "com.sun.kvem.midp.pim.PIMBridge";
            }
            boolean isExcThrown = false;
            try {
                instance = (PIMHandler) Class.forName(className).newInstance();
            } catch (ClassNotFoundException e) {
                isExcThrown = true;
            } catch (Error e) {
                isExcThrown = true;
            } catch (IllegalAccessException e) {
                isExcThrown = true;
            } catch (InstantiationException e) {
                isExcThrown = true;
            }
            if (isExcThrown) {
                throw new Error("PIM handler could not be initialized.");
            }
        }

        return instance;
    
public abstract byte[]getListElement(java.lang.Object listHandle, java.lang.Object elementKey)
Get the data for a list element.

param
listHandle handle of list
param
elementKey the key of the requested element
return
a byte array containing the element data in a supported format
throws
PIMException in case of I/O error.

public abstract java.lang.String[]getListElementCategories(java.lang.Object listHandle, java.lang.Object elementKey)
Get categories for the specified list element.

param
listHandle handle of list
param
elementKey the key of the requested element
return
an array of categories names
throws
PIMException in case of I/O error.

public abstract java.lang.Object[]getListKeys(java.lang.Object listHandle)
Get list element keys.

param
listHandle handle of list
return
an array of objects representing PIM element keys. These keys are to be passed to getListElement() and commitListElement().
throws
PIMException in case of I/O error.

public abstract java.lang.String[]getListNames(int listType)
Get the supported list names for the given list type. All list elements must be unique within the list.

param
listType the type of the list
return
a non-null array of supported list names. A copy of this array is returned by PIM.listPIMLists()

public abstract intgetMaximumValues(java.lang.Object listHandle, int field)
Get the maximum number of values that can be stored in the given field.

param
listHandle handle of list
param
field the field type
return
the maximum value

public abstract intgetStringArraySize(java.lang.Object listHandle, int field)
Checks if size of the string array.

param
listHandle handle of list
param
field the field number
return
size of the string array

public abstract int[]getSupportedArrayElements(java.lang.Object listHandle, int field)
Gets the array of supported elements.

param
listHandle handle of list
param
field the field number
return
array of supported elements

public abstract int[]getSupportedAttributes(java.lang.Object listHandle, int field)
Gets the supported attributes for the given field.

param
listHandle handle of list
param
field identifier of field
return
array of supported attributes of the field

public abstract intgetSupportedAttributesMask(java.lang.Object listHandle, int field)
Gets a mask containing all possible attributes for the given field.

param
listHandle handle of list
param
field the field number
return
supported attribute mask

public abstract int[]getSupportedFields(java.lang.Object listHandle)
Gets all fields that are supported in this list. All fields supported by this list, including both standard and extended, are returned in this array.

param
listHandle handle of list
return
an int array containing all fields supported by this list. The order of the fields returned is unspecified. If there are no supported fields, a zero-length array is returned.

public abstract booleanhasDefaultValue(java.lang.Object listHandle, int field)
Checks if field has default value.

param
listHandle handle of list
param
field identifier of field
return
true if field supported

public abstract booleanisSupportedArrayElement(java.lang.Object listHandle, int field, int arrayElement)
Checks if the array element is supported.

param
listHandle handle of list
param
field the field number
param
arrayElement the element identifier
return
true if attribute element is supported

public abstract booleanisSupportedAttribute(java.lang.Object listHandle, int field, int attribute)
Checks if attribute is supported.

param
listHandle handle of list
param
field the field number
param
attribute identifier of attribute
return
true if attribute is supported

public abstract booleanisSupportedField(java.lang.Object listHandle, int field)
Checks if field is supported in list.

param
listHandle handle of list
param
field identifier of field
return
true if field supported

public abstract java.lang.ObjectopenList(int listType, java.lang.String listName, int openMode)
Opens list.

param
listType the type of the list
param
listName the name of the list
param
openMode open mode
return
list handle that will be used to access this list
throws
PIMException in case of I/O error.

public longparseDate(java.lang.String s)
Converts date in format yyyy-MM-dd or yyyyMMdd to milliseconds.

param
s date in format yyyy-MM-dd or yyyyMMdd
return
number of milliseconds

        Calendar local_calendar =
            Calendar.getInstance();

        // reset calendar to the state it is in composeDate method to get
        // the same values for hours, minutes, seconds and milliseconds. 
        Date cldc_date = new Date(0);
        local_calendar.setTime(cldc_date);

        int year, month, day;
        if (s.indexOf('-") != -1) { // yyyy-MM-dd
            year =  Integer.parseInt(s.substring(0, 4));
            month = Integer.parseInt(s.substring(5, 7));
            day =   Integer.parseInt(s.substring(8, 10));
        } else { // yyyyMMdd
            year =  Integer.parseInt(s.substring(0, 4));
            month = Integer.parseInt(s.substring(4, 6));
            day =   Integer.parseInt(s.substring(6, 8));
        }

        local_calendar.set(Calendar.YEAR, year);
        local_calendar.set(Calendar.MONTH, month - 1);
        local_calendar.set(Calendar.DAY_OF_MONTH, day);

        return (local_calendar.getTime()).getTime();
    
public longparseDateTime(java.lang.String s)
Converts date/time in format yyyyMMddTHHmmss(Z) to milliseconds.

param
s date/time in format yyyyMMddTHHmmss(Z)
return
number of milliseconds

        Calendar local_calendar;
        if (s.length() > 15 && 
            s.charAt(15) == 'Z") { // absolute time
            local_calendar =
                Calendar.getInstance(TimeZone.getTimeZone("GMT"));
        } else {
            local_calendar =
                Calendar.getInstance();
        }
        int year, month, day, hour, min, sec; // yyyyMMddTHHmmss
        year =  Integer.parseInt(s.substring(0, 4));
        month = Integer.parseInt(s.substring(4, 6));
        day =   Integer.parseInt(s.substring(6, 8));
        hour =  Integer.parseInt(s.substring(9, 11));
        min =   Integer.parseInt(s.substring(11, 13));
        sec =   Integer.parseInt(s.substring(13, 15));

        local_calendar.set(Calendar.YEAR, year);
        local_calendar.set(Calendar.MONTH, month - 1);
        local_calendar.set(Calendar.DAY_OF_MONTH, day);
        local_calendar.set(Calendar.HOUR_OF_DAY, hour);
        local_calendar.set(Calendar.MINUTE, min);
        local_calendar.set(Calendar.SECOND, sec);
        local_calendar.set(Calendar.MILLISECOND, 0);

        return (local_calendar.getTime()).getTime();
    
private java.lang.Stringprefix_0(java.lang.String str)
Adds the "0" prefix to one-digit number in string representation.

param
str number in string representation
return
two-digit number in string representation


                                 
        
        String returnValue = "";
        if (str.length() < 2) { // x convert to 0x
            returnValue = "0";
        }
        returnValue += str;
        return returnValue;
    
public abstract voidrenameCategory(java.lang.Object listHandle, java.lang.String currentCategory, java.lang.String newCategory)
Rename a category.

param
listHandle handle of list
param
currentCategory current category name
param
newCategory new category name
throws
PIMException If an error occurs or the list is no longer accessible or closed.
see
#getCategories