org.mobicents.csapi.jr.slee.gms
Interface IpMailboxConnection

All Superinterfaces:

IpServiceConnection

public interface IpMailboxConnection
extends IpServiceConnection

This class represents the Parlay < IpMailboxConnection > interface

Method Summary

void	close() This method closes the mailbox.
void	createFolder(java.lang.String folderID) This method creates a new folder in the mailbox.
int	getInfoAmount() This method returns the number of mailbox information properties of the specified mailbox.
TpMailboxInfoProperty[]	getInfoProperties(int firstProperty, int numberOfProperties) This method returns the properties of a mailbox.
IpMailboxFolderConnection	getIpMailboxFolderConnection(TpMailboxFolderIdentifier mailboxFolderIdentifier) Obtains Access To a IpMailboxFolderConnection interface
void	lock() This method locks the mailbox so that only the requesting application can have access to this mailbox.
TpMailboxFolderIdentifier	openFolder(java.lang.String folderID) This method opens a folder for the application, and returns a folder session ID and a reference to the interface of the folder opened.
void	remove(TpAddress mailboxID, java.lang.String authenticationInfo) This method removes a mailbox from the messaging system for the application.
void	setInfoProperties(int firstProperty, TpMailboxInfoProperty[] mailboxInfoProperties) Sets the properties of a mailbox.
void	unlock() This method unlocks a previously locked mailbox.

Methods inherited from interface org.mobicents.csapi.jr.slee.IpServiceConnection

closeConnection

Method Detail

close

void close()
           throws TpCommonExceptions,
                  javax.slee.resource.ResourceException

This method closes the mailbox. After closing, the interfaces to the mailbox and any associated folders are automatically de-assigned and are no longer valid. Any open folders will also be automatically closed.

Throws:

TpCommonExceptions

javax.slee.resource.ResourceException

lock

void lock()
          throws TpCommonExceptions,
                 P_GMS_LOCKING_LOCKED_MAILBOX,
                 javax.slee.resource.ResourceException

This method locks the mailbox so that only the requesting application can have access to this mailbox. Updates to the mailbox by other applications or the network are not permitted until the mailbox has been unlocked - attempts to do so result in the error code P_GMS_MAILBOX_LOCKED. When the application exits, however, all mailboxes locked by the application are unlocked automatically. The service returns an error code P_GMS_LOCKING_LOCKED_MAILBOX when the application attempts to lock a mailbox that is locked.

Throws:

TpCommonExceptions

P_GMS_LOCKING_LOCKED_MAILBOX

javax.slee.resource.ResourceException

unlock

void unlock()
            throws TpCommonExceptions,
                   P_GMS_UNLOCKING_UNLOCKED_MAILBOX,
                   P_GMS_CANNOT_UNLOCK_MAILBOX,
                   javax.slee.resource.ResourceException

This method unlocks a previously locked mailbox. An error is returned if the mailbox is already unlocked.

Throws:

TpCommonExceptions

P_GMS_UNLOCKING_UNLOCKED_MAILBOX

P_GMS_CANNOT_UNLOCK_MAILBOX

javax.slee.resource.ResourceException

getInfoAmount

int getInfoAmount()
                  throws TpCommonExceptions,
                         javax.slee.resource.ResourceException

This method returns the number of mailbox information properties of the specified mailbox.

Returns:

numberOfProperties The number of properties associated with the folder. The number of properties is zero or positive.

Throws:

TpCommonExceptions

javax.slee.resource.ResourceException

getInfoProperties

TpMailboxInfoProperty[] getInfoProperties(int firstProperty,
                                          int numberOfProperties)
                                          throws TpCommonExceptions,
                                                 P_GMS_NUMBER_NOT_POSITIVE,
                                                 javax.slee.resource.ResourceException

This method returns the properties of a mailbox.

Parameters:

firstProperty - This is the first property of interest. This number represents the starting point where the first property of the list to be retrieved from the mailbox is located. Properties are numbered from zero.

numberOfProperties - The number of properties to return. If the value of this parameter is zero, then all properties will be returned. Otherwise, the value must be a positive number. If the number is not positive, the error code P_GMS_NUMBER_NOT_POSITIVE is returned.

Returns:

mailboxInfoProperties The mailbox information properties (names and values) present in the folder.

Throws:

TpCommonExceptions

P_GMS_NUMBER_NOT_POSITIVE

javax.slee.resource.ResourceException

setInfoProperties

void setInfoProperties(int firstProperty,
                       TpMailboxInfoProperty[] mailboxInfoProperties)
                       throws TpCommonExceptions,
                              P_GMS_PROPERTY_NOT_SET,
                              P_GMS_MAILBOX_LOCKED,
                              javax.slee.resource.ResourceException

Sets the properties of a mailbox.

Parameters:

firstProperty - This is the first property of interest. This number represents the starting point where the first property of the list to be updated in the mailbox is located. Properties are numbered from zero.

mailboxInfoProperties - This specifies the mailbox information properties (names and values) to be set in the mailbox. If the properties cannot be changed, then the error code P_GMS_PROPERTY_NOT_SET is returned.

Throws:

TpCommonExceptions

P_GMS_PROPERTY_NOT_SET

P_GMS_MAILBOX_LOCKED

javax.slee.resource.ResourceException

getIpMailboxFolderConnection

IpMailboxFolderConnection getIpMailboxFolderConnection(TpMailboxFolderIdentifier mailboxFolderIdentifier)
                                                       throws javax.slee.resource.ResourceException

Obtains Access To a IpMailboxFolderConnection interface

Returns:

A IpMailboxFolderConnection interface

Throws:

ResourceException - If it is not possible to create the connection

openFolder

TpMailboxFolderIdentifier openFolder(java.lang.String folderID)
                                     throws TpCommonExceptions,
                                            P_GMS_FOLDER_IS_OPEN,
                                            P_GMS_INVALID_FOLDER_ID,
                                            P_GMS_MAILBOX_LOCKED,
                                            javax.slee.resource.ResourceException

This method opens a folder for the application, and returns a folder session ID and a reference to the interface of the folder opened. The application can open more than one folder at the same time. The application is not allowed to open the same folder more than once at the same time. If the folder is already open, the error code P_GMS_FOLDER_IS_OPEN is returned.

Parameters:

folderID - Specifies the identity of the folder. If the folder ID given is not present, the error code P_GMS_INVALID_FOLDER_ID is returned.

Returns:

folderReference Specifies the reference to the opened folder.

Throws:

TpCommonExceptions

P_GMS_FOLDER_IS_OPEN

P_GMS_INVALID_FOLDER_ID

P_GMS_MAILBOX_LOCKED

javax.slee.resource.ResourceException

createFolder

void createFolder(java.lang.String folderID)
                  throws TpCommonExceptions,
                         P_GMS_INVALID_FOLDER_ID,
                         P_GMS_MAILBOX_LOCKED,
                         javax.slee.resource.ResourceException

This method creates a new folder in the mailbox.

Parameters:

folderID - Specifies the identity of the folder. If the folder ID given is already present, the error code P_GMS_INVALID_FOLDER_ID is returned.

Throws:

TpCommonExceptions

P_GMS_INVALID_FOLDER_ID

P_GMS_MAILBOX_LOCKED

javax.slee.resource.ResourceException

remove

void remove(TpAddress mailboxID,
            java.lang.String authenticationInfo)
            throws TpCommonExceptions,
                   P_GMS_INSUFFICIENT_PRIVILEGE,
                   P_GMS_INVALID_MAILBOX,
                   P_GMS_MAILBOX_LOCKED,
                   P_GMS_MAILBOX_OPEN,
                   P_GMS_INVALID_AUTHENTICATION_INFORMATION,
                   javax.slee.resource.ResourceException

This method removes a mailbox from the messaging system for the application. Authentication information may be needed to remove the mailbox. If the application does not have sufficient privilege to remove the mailbox, the error code P_GMS_INSUFFICIENT_PRIVILEGE is returned.

Parameters:

mailboxID - Specifies the identity of the mailbox. If the mailbox chosen is invalid, the error code P_GMS_INVALID_MAILBOX is returned. If the mailbox is locked then the error code P_GMS_MAILBOX_LOCKED is returned. If the mailbox is open then the error code P_GMS_MAILBOX_OPEN is returned.

authenticationInfo - Authentication information needed for the application to remove a mailbox from the messaging system, such as a key or password. If the authentication process is considered strong enough for the application to gain access to the mailbox, then the authentication information will be an empty string. If the authentication information is not valid, the error code P_GMS_INVALID_AUTHENTICATION_INFORMATION is returned.

Throws:

TpCommonExceptions

P_GMS_INSUFFICIENT_PRIVILEGE

P_GMS_INVALID_MAILBOX

P_GMS_MAILBOX_LOCKED

P_GMS_MAILBOX_OPEN

P_GMS_INVALID_AUTHENTICATION_INFORMATION

javax.slee.resource.ResourceException