net.rim.blackberry.api.pdap
Class BlackBerryPIM

java.lang.Object
  extended by javax.microedition.pim.PIM
      extended by net.rim.blackberry.api.pdap.BlackBerryPIM

public abstract class BlackBerryPIM
extends PIM

Class for accessing the PIM databases on a BlackBerry device.

Contains static methods for performing operations on lists.

For more information about the personal information management (PIM) API, refer to The PDA Profile specification (JSR-000075) for the J2ME(TM) Platform.

See Also:
PIM, PIMItem, PIMList
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.2.0

Field Summary
Category: Signed static int MEMO_LIST
          Represents the Memo List type.
Category: Signed static int REMOVE_NON_EMPTY_LIST
          Constant indicating that a non-empty PIM list can be removed.
 
Fields inherited from class javax.microedition.pim.PIM
CONTACT_LIST, EVENT_LIST, READ_ONLY, READ_WRITE, TODO_LIST, WRITE_ONLY
 
Constructor Summary
Category: Signed protected BlackBerryPIM()
          BlackBerryPIM objects should be created using the getInstance() method.
 
Method Summary
Category: Signed  void addListChangeListener(ListChangeListener listener)
          Adds a ListChangeListener to be notified of list change events.
Category: Signed abstract  long createPIMList(int type, String name)
          Creates a PIMList.
Category: Signed abstract  boolean isCreatePIMListSupported(int type)
          Returns whether or not creating a PIMList of a specified type is supported.
Category: Signed abstract  boolean isRemovePIMListSupported(int type)
          Returns whether or not removing a PIMList of a specified type is supported.
Category: Signed abstract  PIMList openPIMList(int pimListType, int mode, long uid)
          Opens a PIMList by its UID.
Category: Signed  BlackBerryPIMList openUnifiedPIMList(int pimListType, int mode)
          Opens a "unified" PIMList of all available PIMLists of the requested type.
Category: Signed abstract  BlackBerryPIMList openUnifiedPIMList(int pimListType, int mode, String[] names)
          Opens a "unified" PIMList of the lists with the provided names.
Category: Signed abstract  BlackBerryPIMList openUnifiedPIMList(int pimListType, int mode, long[] uids)
          Opens a "unified" PIMList of the lists with the provided UIDs.
Category: Signed  void removeListChangeListener(ListChangeListener listener)
          Removes a ListChangeListener from being notified of list change events.
Category: Signed abstract  void removePIMList(int type, String name)
          Removes an empty PIMList.
Category: Signed abstract  void removePIMList(int type, String name, int flags)
          Removes a PIMList.
Category: Signed abstract  void removePIMList(int type, long uid)
          Removes an empty PIMList.
Category: Signed abstract  void removePIMList(int type, long uid, int flags)
          Removes a PIMList.
 
Methods inherited from class javax.microedition.pim.PIM
fromSerialFormat, getInstance, listPIMLists, openPIMList, openPIMList, supportedSerialFormats, toSerialFormat
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 



Field Detail

MEMO_LIST

public static final int MEMO_LIST
Represents the Memo List type.

See Also:
Constant Field Values
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.2.0

REMOVE_NON_EMPTY_LIST

public static final int REMOVE_NON_EMPTY_LIST
Constant indicating that a non-empty PIM list can be removed.

See Also:
Constant Field Values
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 6.0.0


Constructor Detail

BlackBerryPIM

protected BlackBerryPIM()
BlackBerryPIM objects should be created using the getInstance() method.

Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.2.0


Method Detail

addListChangeListener

public void addListChangeListener(ListChangeListener listener)
Adds a ListChangeListener to be notified of list change events.

If the specified listener is already present in the list of listeners then it will NOT be added again and this method will return as if successful.

The invocations of the methods of the specified listener will occur on the event thread of the calling application. Therefore, if the event thread of the application is no longer alive or is stalled for some other reason then the events will not be delivered. Also, at the time this method is invoked it is required that there be an Application instance returned from Application.getApplication().

Parameters:
listener - the listener to add.
Throws:
NullPointerException - if listener is null.
IllegalStateException - if Application.getApplication() returns null or throws an exception, indicating that the current application is not set.
See Also:
BlackBerryPIM.removeListChangeListener(ListChangeListener)
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.6.0

removeListChangeListener

public void removeListChangeListener(ListChangeListener listener)
Removes a ListChangeListener from being notified of list change events.

If the specified listener is null or is not in the list of listeners then this method does nothing and will return as if successful.

Parameters:
listener - the listener to remove.
See Also:
BlackBerryPIM.addListChangeListener(ListChangeListener)
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 4.6.0

openPIMList

public abstract PIMList openPIMList(int pimListType,
                                    int mode,
                                    long uid)
                             throws PIMException
Opens a PIMList by its UID. It may be preferable to reference a PIMList by its UID instead of its name because a UID is more constant. The name of a PIMList can change at any time, such as by the user changing the name of the service using the BlackBerry Desktop Software. Also, a different name may be assigned to the same PIMList after a software upgrade. In contrast, a PIMList's UID does not change during the lifetime of the PIMList and remains the same after the device software is upgraded. Applications that maintain a parallel database will want to reference the PIMList by its UID instead of its name in order to maintain referential integrity.

Parameters:
pimListType - the PIM list type to open; valid values include PIM.CONTACT_LIST, PIM.EVENT_LIST, PIM.TODO_LIST, and BlackBerryPIM.MEMO_LIST.
mode - the mode in which the List is opened; must be one of PIM.READ_ONLY, PIM.READ_WRITE, or PIM.WRITE_ONLY.
uid - the UID of the list to open.
Returns:
the PIM list for the indicated PIM list type with the specified UID; never returns null.
Throws:
PIMException - If the list is not available, the operation is unsupported or an error occurs.
SecurityException - if the application is not given permissions that match the requested mode.
IllegalArgumentException - If an invalid mode is provided as a parameter or if pimListType is not a valid PIM list type.
See Also:
PIM.openPIMList(int, int), PIM.openPIMList(int, int, String), PIMList UIDs
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 5.0.0

openUnifiedPIMList

public BlackBerryPIMList openUnifiedPIMList(int pimListType,
                                            int mode)
                                     throws PIMException
Opens a "unified" PIMList of all available PIMLists of the requested type. This method simply invokes BlackBerryPIM.openUnifiedPIMList(int, int, String[]) with the specified parameters and the list of names returned from PIM.listPIMLists(int).

Parameters:
pimListType - the PIM list type to open; valid values include PIM.CONTACT_LIST, PIM.EVENT_LIST, PIM.TODO_LIST, and BlackBerryPIM.MEMO_LIST.
mode - the mode in which the List is opened; must be one of PIM.READ_ONLY, PIM.READ_WRITE, or PIM.WRITE_ONLY.
Returns:
the unified PIMList for the indicated PIM list; never returns null.
Throws:
PIMException - If at least one of the lists in the unification is not available, the operation is unsupported or an error occurs.
SecurityException - if the application is not given permissions that match the requested mode.
IllegalArgumentException - If an invalid mode is provided as a parameter, or if pimListType is not a valid PIM list type.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 5.0.0

openUnifiedPIMList

public abstract BlackBerryPIMList openUnifiedPIMList(int pimListType,
                                                     int mode,
                                                     String[] names)
                                              throws PIMException
Opens a "unified" PIMList of the lists with the provided names. The returned PIMList will provide access to all PIMItems in the each of the named lists as if they were in the same list. If the specified list of names has exactly 1 element, then this method simply invokes PIM.openPIMList(int, int, String) with the specified parameters and the String at index 0 of the array. If a name occurs twice in the array then it will be treated as if it were only present once.

Parameters:
pimListType - the PIM list type to open; valid values include PIM.CONTACT_LIST, PIM.EVENT_LIST, PIM.TODO_LIST, and BlackBerryPIM.MEMO_LIST.
mode - the mode in which the List is opened; must be one of PIM.READ_ONLY, PIM.READ_WRITE, or PIM.WRITE_ONLY.
names - the names of the lists to include in the returned unified PIMList; each value of this array must be equal to one of the strings returned from PIM.listPIMLists(int) when specified the same pimListType; if the array has zero length then a PIMList with zero items will be returned.
Returns:
the unified PIMList for the indicated PIM list type with the specified names; never returns null.
Throws:
PIMException - If at least one of the named lists is not available, the operation is unsupported or an error occurs.
SecurityException - if the application is not given permissions that match the requested mode.
IllegalArgumentException - If an invalid mode is provided as a parameter, or if pimListType is not a valid PIM list type.
NullPointerException - if names==null or any element of names is null.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 5.0.0

openUnifiedPIMList

public abstract BlackBerryPIMList openUnifiedPIMList(int pimListType,
                                                     int mode,
                                                     long[] uids)
                                              throws PIMException
Opens a "unified" PIMList of the lists with the provided UIDs. The returned PIMList will provide access to all PIMItems in the each of the specific lists as if they were in the same list. If the specified list of UIDs has exactly 1 element, then this method simply invokes BlackBerryPIM.openPIMList(int, int, long) with the specified parameters and the UID at index 0 of the array. If a UID occurs twice in the array then it will be treated as if it were only present once.

Parameters:
pimListType - the PIM list type to open; valid values include PIM.CONTACT_LIST, PIM.EVENT_LIST, PIM.TODO_LIST, and BlackBerryPIM.MEMO_LIST.
mode - the mode in which the List is opened; must be one of PIM.READ_ONLY, PIM.READ_WRITE, or PIM.WRITE_ONLY.
uids - the UIDs of the lists to include in the returned unified PIMList; each value of this array must be equal to the UID of one of the PIMLists whose names are returned from PIM.listPIMLists(int) when specified the same pimListType; if the array has zero length then a PIMList with zero items will be returned.
Returns:
the unified PIMList for the indicated PIM list type with the specified UIDs; never returns null.
Throws:
PIMException - If at least one of the UIDs does not map to a PIMList or the PIMList is not available, the operation is unsupported or an error occurs.
SecurityException - if the application is not given permissions that match the requested mode.
IllegalArgumentException - If an invalid mode is provided as a parameter, or if pimListType is not a valid PIM list type.
NullPointerException - if uids==null.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 5.0.0

createPIMList

public abstract long createPIMList(int type,
                                   String name)
                            throws PIMException
Creates a PIMList. Currently, this method operates only on contact lists (PIM.CONTACT_LIST). If a PIMList with the given name of the given type already exists, the new PIMList is created, but the name is modified to be unique for its type. Therefore, after invoking this method, you should use the PIMList's UID to access the PIMList.

Parameters:
type - The PIMList type. Currently, must be PIM.CONTACT_LIST.
name - The name of the PIMList to create.
Returns:
The UID of the PIMList.
Throws:
PIMException - if there is an error in creating the PIMList.
IllegalArgumentException - if the name is null or empty.
UnsupportedOperationException - if the PIMList creation is not supported.
SecurityException - if callers are not allowed to access the PIM API.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 6.0.0

isCreatePIMListSupported

public abstract boolean isCreatePIMListSupported(int type)
Returns whether or not creating a PIMList of a specified type is supported.

Parameters:
type - The PIMList type.
Returns:
true if creating a PIMList of the specified type is supported, false otherwise. Currently, returns true only for PIM.CONTACT_LIST.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 6.0.0

isRemovePIMListSupported

public abstract boolean isRemovePIMListSupported(int type)
Returns whether or not removing a PIMList of a specified type is supported.

Parameters:
type - The PIMList type.
Returns:
true if removing a PIMList of the specified type is supported, false otherwise. Currently, returns true only for PIM.CONTACT_LIST.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 6.0.0

removePIMList

public abstract void removePIMList(int type,
                                   long uid,
                                   int flags)
                            throws BlackBerryPIMRemovalException
Removes a PIMList. Currently, this method operates only on contact lists (PIM.CONTACT_LIST).

Parameters:
type - The PIMList type. Currently, must be PIM.CONTACT_LIST.
uid - The UID of the PIMList to remove.
flags - A bitwise combination of flags to alter the behavior of the removal; for example, you must specify BlackBerryPIM.REMOVE_NON_EMPTY_LIST to allow the removal of a non-empty PIMList.
Throws:
BlackBerryPIMRemovalException - if the PIMList removal fails; a reason code is given.
SecurityException - if callers are not allowed to access the PIM API.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 6.0.0

removePIMList

public abstract void removePIMList(int type,
                                   String name)
                            throws BlackBerryPIMRemovalException
Removes an empty PIMList. Currently, this method operates only on contact lists (PIM.CONTACT_LIST).

Parameters:
type - The PIMList type. Currently, must be PIM.CONTACT_LIST.
name - The name of the PIMList to remove.
Throws:
BlackBerryPIMRemovalException - if the PIMList removal fails; a reason code is given.
SecurityException - if callers are not allowed to access the PIM API.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 6.0.0

removePIMList

public abstract void removePIMList(int type,
                                   long uid)
                            throws BlackBerryPIMRemovalException
Removes an empty PIMList. Currently, this method operates only on contact lists (PIM.CONTACT_LIST).

Parameters:
type - The PIMList type. Currently, must be PIM.CONTACT_LIST.
uid - The UID of the PIMList to remove.
Throws:
BlackBerryPIMRemovalException - if the PIMList removal fails; a reason code is given.
SecurityException - if callers are not allowed to access the PIM API.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 6.0.0

removePIMList

public abstract void removePIMList(int type,
                                   String name,
                                   int flags)
                            throws BlackBerryPIMRemovalException
Removes a PIMList. Currently, this method operates only on contact lists (PIM.CONTACT_LIST).

Parameters:
type - The PIMList type. Currently, must be PIM.CONTACT_LIST.
name - The name of the PIMList to remove.
flags - A bitwise combination of flags to alter the behavior of the removal; for example, you must specify BlackBerryPIM.REMOVE_NON_EMPTY_LIST to allow the removal of a non-empty PIMList.
Throws:
BlackBerryPIMRemovalException - if the PIMList removal fails; a reason code is given.
SecurityException - if callers are not allowed to access the PIM API.
Category:
Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.
Since:
BlackBerry API 6.0.0





Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.