net.rim.blackberry.api.mail
Class Session

java.lang.Object
  extended by net.rim.blackberry.api.mail.Session

public final class Session
extends Object

Provides access to email services, storage, and transport.

See Also:
Service, Store, Transport
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 3.6.0

Method Summary
Category: Signed static void addDefaultSessionListener(DefaultSessionListener dl)
          Registers a listener for Default Session change notification.
Category: Signed static void addViewListener(ViewListener vl)
          Registers a listener for view notification.
Category: Signed static Session getDefaultInstance()
          Retrieves this device's default session.
Category: Signed static Session getDefaultInstance(ServiceConfiguration sc)
          Retrieves default session based on provided service configruation.
Category: Signed static Session getInstance(ServiceConfiguration sc)
          Retrieves session by provided service configuration.
Category: Signed  ServiceConfiguration getServiceConfiguration()
          Retrieves the service configuration for this service.
Category: Signed  Store getStore()
          Retrieves a Store instance to access message storage on this device.
Category: Signed  Transport getTransport()
          Retrieves a Transport instanace to access the email transport protocol on the handheld.
Category: Signed static void removeDefaultSessionListener(DefaultSessionListener dl)
          De-registers a default Session listener.
Category: Signed static void removeViewListener(ViewListener vl)
          De-registers a view notification listener.
Category: Signed static Session waitForDefaultSession()
          Retrieves this device's default mail service (blocking).
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 



Method Detail

getDefaultInstance

public static Session getDefaultInstance()
Retrieves this device's default session.

Use this method to retrieve the default session associated with the handheld (typically the enterprise email account).

There is a possible timing issue with startup. If the various service book entries are not yet present on the handheld, this call returns null. This does not always mean that no service is available; it is possible that the service just is not yet registered.

Returns:
The default session instance associated with the handheld, or null if one can't be created (for instance, due to lack of Service Book configuration information on the device).
Throws:
ControlledAccessException - if the application is not granted to access the default email service.
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 3.6.0

getInstance

public static Session getInstance(ServiceConfiguration sc)
Retrieves session by provided service configuration.

Parameters:
sc - Service configuration information from which to retrieve service.
Returns:
Session associated with provided service configuration, or null if no such service.
Throws:
ControlledAccessException - if the application is not granted to access the email service.
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.0.0

waitForDefaultSession

public static Session waitForDefaultSession()
                                     throws NoSuchServiceException
Retrieves this device's default mail service (blocking).

Note: This call blocks indefinitely if no service is available.

Throws:
NoSuchServiceException - If the default service can't be instantiated (usually due to lack of Service Book configuration information on the device).
ControlledAccessException - if the application is not granted to access the email service.
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 3.6.0

getDefaultInstance

public static Session getDefaultInstance(ServiceConfiguration sc)
Retrieves default session based on provided service configruation.

Parameters:
sc - Service configuration for which to retrieve the mail service.
Returns:
Session instance associated with the configuration provided, or null if one can't be created (for instance, because the device doesn't contain valid service book information for the named service).
Throws:
ControlledAccessException - if the application is not granted to access the email service.
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 3.6.0

getServiceConfiguration

public ServiceConfiguration getServiceConfiguration()
Retrieves the service configuration for this service.

Returns:
Service configuration for this service.
Throws:
ControlledAccessException - if the application is not granted to access the email service or the email functionality on the device.
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 3.6.0

getStore

public Store getStore()
Retrieves a Store instance to access message storage on this device.

Returns:
Instance of the store.
Throws:
ControlledAccessException - if the application is not granted to access the email service or the email functionality on the device..
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 3.6.0

getTransport

public Transport getTransport()
Retrieves a Transport instanace to access the email transport protocol on the handheld.

Returns:
Transport instance.
Throws:
ControlledAccessException - if the application is not granted to access the email service or the email functionality on the device.
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 3.6.0

addViewListener

public static void addViewListener(ViewListener vl)
Registers a listener for view notification.

Parameters:
vl - View listener to add.
Throws:
ControlledAccessException - if the application is not granted to access the email functionality on the device.
NullPointerException - if ViewListener 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 4.0.0

removeViewListener

public static void removeViewListener(ViewListener vl)
De-registers a view notification listener.

Parameters:
v1 - View listener to remove.
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.0.0

addDefaultSessionListener

public static void addDefaultSessionListener(DefaultSessionListener dl)
Registers a listener for Default Session change notification.

Parameters:
dl - DefaultSessionListener listener to add.
Throws:
NullPointerException - if the listener is null.
ControlledAccessException - if the application is not granted to access the email functionality on the device.
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

removeDefaultSessionListener

public static void removeDefaultSessionListener(DefaultSessionListener dl)
De-registers a default Session listener.

Parameters:
d1 - DefaultSessionListener to remove. If the specified listener is not registered or if the parameter is null, this method silently returns with no action.
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





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.