javax.microedition.swm

Interface SuiteManager

public interface SuiteManager

Suite manager interface. Implementations are delivered by the ManagerFactory.

Method Summary

Methods

Modifier and Type	Method and Description
void	addSuiteListener(SuiteListener theListener) Adds a SuiteListener.
Suite	getSuite(java.lang.String vendor, java.lang.String name) Returns the instance of the installed Suite.
SuiteInstaller	getSuiteInstaller(byte[] instData, int offset, int length, boolean ignoreUpdateLock) Returns SuiteInstaller.
SuiteInstaller	getSuiteInstaller(java.lang.String locationUrl, boolean ignoreUpdateLock) Returns SuiteInstaller.
java.util.List<Suite>	getSuites(SuiteType type) Requests a list of installed suites of specified type.
void	removeSuite(Suite suite, boolean ignoreRemoveLock) Removes a Suite.
void	removeSuiteListener(SuiteListener theListener) Removes a SuiteListener.

Method Detail

getSuiteInstaller

SuiteInstaller getSuiteInstaller(java.lang.String locationUrl,
                               boolean ignoreUpdateLock)
                                 throws java.lang.SecurityException,
                                        java.lang.IllegalArgumentException

Returns SuiteInstaller. To be able to retreive the application installer, caller application should request javax.microedition.swm.SWMPermission("client", "installation") or javax.microedition.swm.SWMPermission ("crossClient", "installation") permission (see SWMPermission for details).

The function can result in network access for the application descriptor acquiring.

The resulting SuiteInstaller can be used for both, the installation of an application suite being new to the device (in this case the parameter ignoreUpdateLock, see below, is without meaning), or the update of an application suite that had already been installed on the device before.

Parameters:

locationUrl - URL indicating the network location where the jad/jar files can be retrieved from

ignoreUpdateLock - if true the application suite components will be updated even if lock for update is set. This option should be used with caution and programmers should always set this parameter to false.

Returns:

instance of SuiteInstaller

Throws:

java.lang.SecurityException - if the caller application does not have the required javax.microedition.swm.SWMPermission permission

java.lang.IllegalArgumentException - if the locationUrl is not a valid URL, or the server is not reachable

getSuiteInstaller

SuiteInstaller getSuiteInstaller(byte[] instData,
                               int offset,
                               int length,
                               boolean ignoreUpdateLock)
                                 throws java.lang.SecurityException,
                                        java.lang.IllegalArgumentException

Returns SuiteInstaller. To be able to retreive the application installer, caller application should request javax.microedition.swm.SWMPermission("client", "installation") or javax.microedition.swm.SWMPermission ("crossClient", "installation") permission (see SWMPermission for details).

A SuiteInstaller can be used to install the application from an in-memory buffer, where the raw jar file bytes have been brought to before.

The resulting SuiteInstaller can be used for both, the installation of an application suite being new to the device (in this case the parameter ignoreUpdateLock, see below, is without meaning), or the update of an application suite that had already been installed on the device before.

Parameters:

instData - in-memory buffer where the installation data (raw jar bytes) can be retrieved from

offset - offset within the in-memory buffer the installation data will be retrieved from

length - length of the installation data to be retrieved from the in-memory buffer

ignoreUpdateLock - if true the application suite components will be updated even if lock for update is set. This option should be used with caution and programmers should always set this parameter to false.

Returns:

instance of SuiteInstaller

Throws:

java.lang.SecurityException - if the caller application does not have the required javax.microedition.swm.SWMPermission permission

java.lang.IllegalArgumentException - if the byte array is empty, the offset or offset+length exceeds the boundaries of the byte array

getSuite

Suite getSuite(java.lang.String vendor,
             java.lang.String name)

Returns the instance of the installed Suite.

Parameters:

vendor - vendor name of the requested suite

name - the name of the suite

Returns:

Suite instance of the application or null if no application was found

getSuites

java.util.List<Suite> getSuites(SuiteType type)

Requests a list of installed suites of specified type. This list may be empty.

Parameters:

type - must be one of: SuiteType.APPLICATION or SuiteType.LIBRARY

Returns:

a list of Suite instances that may be empty

Throws:

java.lang.IllegalArgumentException - if type is not SuiteType.APPLICATION or SuiteType.LIBRARY

addSuiteListener

void addSuiteListener(SuiteListener theListener)

Adds a SuiteListener. Several listeners can be added, all get notified about state changes of suites.

Parameters:

theListener - SuiteListener to be added

removeSuiteListener

void removeSuiteListener(SuiteListener theListener)

Removes a SuiteListener.

Parameters:

theListener - SuiteListener to be removed

removeSuite

void removeSuite(Suite suite,
               boolean ignoreRemoveLock)
                 throws SuiteLockedException,
                        java.lang.IllegalStateException

Removes a Suite. This is a synchronous method. If it is processed normally (without throwing an exception), it MUST be guaranteed that the specified Suite is removed afterwards.

In case the removal of the suite has been successful, calling isInstalled() for this Suite returns false.

If the suite uses resources being used by other components, those MUST be guaranteed to remain available. Resources MUST NOT be released until they are not in use anymore.

Before a suite can be removed, all applications belonging to this suite MUST be stopped. In particular, an application is not able to remove its own suite using this API.

Parameters:

suite - the suite to be removed

ignoreRemoveLock - if true suite is removed even if it has state flag SuiteStateFlag.REMOVE_DENIED

Throws:

SuiteLockedException - is thrown, if suite is locked and the ignoreRemoveLock parameter is set to false. In some implementation specific cases this exception MAY be also thrown if the ignoreRemoveLock parameter is set to true. For details about when suite is called locked , see SuiteLockedException.

java.lang.IllegalStateException - if the suite has already been removed or if an application of this suite is still running. This does also apply if an application tries to remove its own suite.