3 Installing Suites

This chapter discusses how to install suites using the AMS APIs.

First, any MIDlet that requires permission to install or remove other MIDlets must declare the respective permissions in its JAD descriptor:

MIDlet-Permissions: com.sun.ams.SuiteInstaller.start, com.sun.ams.SuiteInfo.remove

The AMS APIs contain two installer interfaces: AppInstaller and LinkInstaller, both of which extend the base SuiteInstaller interface. Likewise, each installer provides for a listener, AppInstallerListener or LinkInstallerListener, which both extend from the SuiteInstallerListener interface, used to monitor an installer's progress.

SuiteInstaller Interface

The SuiteInstaller interface is a sub-interface that consists of only two methods: one that starts the installation and one that cancels the installation.

void start() throws SecurityException

This method begins the installation of a suite. This method returns immediately; the caller can observe the progress of the installation using a listener. A SecurityException can be thrown if installation of the MIDlet is prohibited.
void cancel()

This method cancels an installation that is in progress.

AppInstaller Interface

The AppInstaller interface is obtained from the AmsFactory class and extends the SuiteInstaller interface, and consists of five methods to initialize an app installation. With each installation, the programmer must provide the location of the app using either a URL that points to a JAR/JAD or a SuiteInfo, and an AppInstallerProgressListener that is called while the app is being installed. In addition, the programmer can provide an optional series of bytes that represents the app icon.

Each initialize() method returns a class that implements the SuiteInfo interface, which is a descriptor of the application that is being downloaded. Note that if the descriptor is not provided (for example, the locationUrl in the initialize() method points to a JAR file instead of a JAD), then the returned SuiteInfo object will return null for all methods except getDownloadUrl() and getSuiteType().

The SuiteInfo object returned by each of the initialize() methods has no suite management methods implemented, so any calls to the following methods results in a RuntimeException:

SuiteInfo.getIcon()
SuiteInfo.getDownloadUrl()
SuiteInfo.remove()
SuiteInfo.getState()
SuiteInfo.setState(int state, boolean value)
SuiteInfo.getSettings()

Once the AppInstaller method is initialized, the programmer can call the start() method to begin the download and installation, monitoring the results with an AppInstallerProgressListener.

Here are the initialize() methods provided by the AppInstaller interface.

SuiteInfo initialize(java.lang.String locationUrl, AppInstallerProgressListener listener)

This method initializes an installer with the URL address of an app's JAD or JAR file and provides an installation progress listener. The function can result in network access. The installation progress listener must be present and ready to handle callback requests, such as querying the user for a valid login and password.
SuiteInfo initialize(java.lang.String locationUrl, AppInstallerProgressListener listener, boolean ignoreUpdateLock)

This method initializes an installer with the URL address of an app's JAD or JAR file and provides an installation progress listener. The function can result in network access. The installation progress listener must be present and ready to handle callback requests, such as querying the user for a valid login and password. This method contains a boolean parameter that, if set to true, ignores an update lock for an app if it is present.
SuiteInfo initialize(java.lang.String locationUrl, byte[] iconBytes, AppInstallerProgressListener listener)

This method initializes an installer with the URL address of an app's JAD or JAR file, a byte array that represents the icon of the app, and an installation progress listener. The function can result in network access. The installation progress listener must be present and ready to handle callback requests, such as querying the user for a valid login and password.
SuiteInfo initialize(java.lang.String jadUrl, java.lang.String jarUrl, AppInstallerProgressListener listener)

This method initializes an installer with the URL address of an app's JAD and JAR file and provides an installation progress listener. The function can result in network access. The installation progress listener must be present and ready to handle callback requests, such as querying the user for a valid login and password.
SuiteInfo initialize(java.lang.String jadUrl, java.lang.String jarUrl, byte[] iconBytes, AppInstallerProgressListener listener)

This method initializes an installer with the URL address of the app's JAD and the URL address of the app's JAR file, a byte array that represents the icon of the app, and an installation progress listener. The function can result in network access. The installation progress listener must be present and ready to handle callback requests, such as querying the user for a valid login and password.
SuiteInfo initialize(SuiteInfo suiteInfo, AppInstallerProgressListener listener) throws UnsupportedServiceException

This method initializes an installer the specified SuiteInfo descriptor, and an installation progress listener. The function is intended to use for installation from local storage but is not limited by such use case. The installation progress listener must be present and ready to handle callback requests, such as querying the user for a valid login and password. As this method is not yet implemented, it persistently throws an UnsupportedServiceException.

If the program must cancel the installation of the app, use the cancel() method.

LinkInstaller Interface

The LinkInstaller is obtained from the AmsFactory class and is used to download a link that references another application. It consists of only one initialize() method. Once the program has initialized a LinkInstaller, call the start() method to begin the download, monitoring the results with an LinkInstallerProgressListener.

SuiteInfo initialize(java.lang.String jadUrl, java.lang.String iconUrl, LinkInstallerProgressListener listener)

This method initializes a link installer with the URL address of a JAD and icon file and provides an installation progress listener. The function can result in network access. The installation progress listener must be present and ready to handle callback requests, such as querying the user for a valid login and password.

If the program must cancel the installation of the link, use the cancel() method.

SuiteInstallerProgressListener Interface

SuiteInstallerProgressListener is a sub-interface that provides progress data for an installer that is downloading an app or a link.

The interface consists of two methods, both of which are called at certain times during installation. One is the done() method, which provides only a single code, the definitions of which can be found in the InstallerErrorCode interface. The other is the updateStatus() method, which identifies the current task as one of the five constants that are shown in Table 3-1, and provides an integer percentage of completeness.

Table 3-1 Progress Constants While Installing a Suite

Name	Description
`DOWNLOADING_BODY`	Install stage: downloading application body.
`DOWNLOADING_DATA`	Install stage: downloading additional application data.
`DOWNLOADING_DESCRIPTOR`	Install stage: downloading application descriptor.
`STORING`	Install stage: storing application.
`VERIFYING`	Install stage: verifying downloaded content.

Here are the two method defined in the SuiteInstallerProgressListener interface:

void done(int errorCode)

This method is called by the installer to report that the installation has completed. The resulting integer code is contained in the InstallerErrorCode class. See "InstallerErrorCode" for more information on installation error codes.
void updateStatus(int stage, int percent)

This method is called by the installer to inform the listener of the current status of the install. The stage is given by an integer constant as shown in Table 3-1. The percent is an integer between 0 and 100.

AppInstallerProgressListener Interface

The AppInstallerProgressListener interface extends SuiteInstallerProgressListener and contains methods that the AppInstaller calls as it is downloading and installing an app. Any of the methods are called to request additional information from the user.

java.lang.String[] getNetworkAccessCredentials()

This method is called to ask user for login and password for network access. Typically the function is used for proxy authorization. This method should return a String array where first element is the login ID and the second element is the password. If the user wants to cancel the installation, the method should return NULL; doing so results in a call to the done() method with the InstallerErrorCodes.CANCEL constant. See "InstallerErrorCode" for more information on installation error codes. The credentials provided are stored and reused, unless the credentials are invalid, at which point the user will be repeatedly asked for a proper login ID and password combination.
java.lang.String[] getResourceAccessCredentials()

This method is called to ask user for login and password for network resource access. This method should return a String array where first element is the login ID and the second element is the password. If the user wants to cancel the installation, the method should return NULL; doing so results in a call to the done() method with the InstallerErrorCodes.CANCEL constant. See "InstallerErrorCode" for more information on installation error codes. The credentials provided are stored and reused, unless the credentials are invalid, at which point the user will be repeatedly asked for a proper login ID and password combination.
boolean confirmUpdate(int status)

This method is called to ask the user to confirm an update of an installed application. The integer status parameter can be one of InstallerErrorCode.OLD_VERSION, InstallerErrorCode.ALREADY_INSTALLED, or InstallerErrorCode.NEW_VERSION. This method should return true if the user wants to continue, or false if the user wants to cancel. Cancelling results in a call to the done() method with the InstallerErrorCodes.CANCEL constant. See "InstallerErrorCode" for more information on installation error codes.
boolean confirmJarDownload(int totalSize)

This method is called to confirm an application download with the specified size in bytes. Dynamic components and RMS data are included as well. This method should return true if the user wants to continue, or false if the user wants to cancel. Cancelling results in a call to the done() method with the InstallerErrorCodes.CANCEL constant. See "InstallerErrorCode" for more information on installation error codes.
boolean keepRMS()

This method is called to ask the user to confirm if the Record Management Store (RMS) data should be kept for new version of an updated suite. This method should return true if the user wants to keep the RMS data for the suite, false otherwise.
boolean confirmAuthPath(java.lang.String[] authPath)

This method is called to ask the user to confirm the authentication path, presented as a String array. The authentication path is a list of certificate authorities. Here, descriptions of all the certificates in the chain should be provided for the user to review and authorize. The method should return true if the user wants to continue, or false if the user wants to cancel. Cancelling results in a call to the done() method with the InstallerErrorCodes.CANCEL constant. See "InstallerErrorCode" for more information on installation error codes.
boolean confirmRedirect(java.lang.String newLocation)

This method is called with the URL when a request to be redirected to a new location is made. The method should return true if user wants to install the application suite from the new location, or false if the user wants to cancel. Cancelling results in a call to the done() method with the InstallerErrorCodes.CANCEL constant. See "InstallerErrorCode" for more information on installation error codes.
boolean confirmUnsignedFxInstall()

This method is called to confirm to the user that they indeed with to install an unsigned JavaFX application. This method should return true if the user wants to continue, or false if the user wants to cancel. Cancelling results in a call to the done() method with the InstallerErrorCodes.CANCEL constant. See "InstallerErrorCode" for more information on installation error codes.
boolean confirmGrantMaximumPermissions(Vector groupNames, boolean hasRisks)

This method is called during an installation or update to ask if the user wants to grant the maximum permissions allowed by MIDP specification to the MIDlet suite. The groupNames parameter is a Vector containing the names of permission groups that match permissions requested by this suite in its JAD or JAR. The hasRisks parameter can be set to true if groupNames contains high risk combinations. The method should return true if the user wants to grant permissions, false otherwise.
boolean confirmCurrentScreenSaverUpdate(java.lang.String name)

This method is called when the current screen saver MIDlet is being updated by a new screen saver MIDlet. The name of the MIDlet is provided. The method should return true if the user agrees with the update, or false if the user wants to stop the installation. Returning false results in a SuiteInstallerProgressListener.done(InstallerErrorCodes.CANCELED) progress update.
boolean confirmCurrentScreenSaverUnset(java.lang.String name)

This method is called when the current screen saver MIDlet is no longer set as the system screen saver. The name of the MIDlet is provided. The method should return true if the user agrees with the unsetting, or false if the user wants to stop the unsetting. Returning false results in a SuiteInstallerProgressListener.done(InstallerErrorCodes.CANCELED) progress update.
boolean confirmPersistentSuiteInstallation()

This method is called during an installation to ask if the user wants to install a permanent MIDlet suite. The method should return true if the user wants to continue, false otherwise.
java.lang.String getRmsEncryptionPassword()

This method is called to request the RMS encryption password from the user.
java.lang.String getRmsDecryptionPassword()

This method is called to request the RMS decryption password from the user.
boolean confirmInstallUnverified()

This method is called to ask the user to confirm an untrusted installation even though the MIDlet suite does not pass verification, likely due to an unknown certificate authority. This functionality is optional and may absent in some configurations. The method should return true if the user agrees with the install, or false if the user wants to stop the install. Returning false results in a SuiteInstallerProgressListener.done(InstallerErrorCodes.CANCELED) progress update.
boolean confirmRebindingServiceProviders(String[] serviceNames)

This method is called if new service providers are installed. The user can then be asked to confirm if he wants to perform rebinding existing applications with these new service providers. The method should return true if the user wants to perform the rebinding, false otherwise.
boolean confirmCertificateImport(Certificate cert)

This method is called to ask the user to confirm that a certificate that the MIDlet suite is signed with may be imported into the internal keystore. This functionality is optional and may absent in some configurations. The method should return true if the user wants to import the certificate, false otherwise.

LinkInstallerProgressListener Interface

The LinkInstallerProgressListener interface extends SuiteInstallerProgressListener and is used for processing link installer notifications, including asking for user credentials, and confirming if the user wants to perform an update. The interface consists of only two methods:

boolean confirmUpdate()

This method is called to ask the user to confirm an update of an installed link. This method should return true if the user wants to continue, or false if the user wants to cancel. If the user cancels, the SuiteInstallerProgressListener.done() method is called with InstallerErrorCodes.CANCELED constant.
java.lang.String[] getNetworkAccessCredentials()

This method is called to ask user for login and password for network access. Typically the function is used for proxy authorization. This method should return a String array where first element is the login ID and the second element is the password. The credentials provided are stored and reused, unless the credentials are invalid, at which point the user will be repeatedly asked for a proper login ID and password combination.

InstallerErrorCode

The InstallerErrorCode provides several constants used by the installation routines. These constants are shown in Table 3-2.

Table 3-2 Installer Error Codes

Constant	Error Code	Description
`ALAA_ALIAS_NOT_FOUND`	78	Application Level Access Authorization: The alias definition is missing.
`ALAA_ALIAS_WRONG`	80	Application Level Access Authorization: The alias definition is wrong.
`ALAA_MULTIPLE_ALIAS`	79	Application Level Access Authorization: An alias has multiple entries that match.
`ALAA_TYPE_WRONG`	77	Application Level Access Authorization: The `MIDlet-Access-Auth-Type` has missing parameters.
`ALREADY_INSTALLED`	39	The JAD matches a version of a suite already installed.
`APP_INTEGRITY_FAILURE_DEPENDENCY_CONFLICT`	69	Application Integrity Failure: two or more dependencies exist on the component with the same name and vendor, but have different versions or hashs.
`APP_INTEGRITY_FAILURE_DEPENDENCY_MISMATCH`	70	Application Integrity Failure: there is a component name or vendor mismatch between the component JAD and IMlet or component JAD that depends on it.
`APP_INTEGRITY_FAILURE_HASH_MISMATCH`	68	Application Integrity Failure: hash mismatch.
`ATTRIBUTE_MISMATCH`	50	A attribute in both the JAD and JAR manifest does not match.
`AUTHORIZATION_FAILURE`	49	Application authorization failure, possibly indicating that the application was not digitally signed.
`CA_DISABLED`	60	Indicates that the trusted certificate authority (CA) for this suite has been disabled for software authorization.
`CANCELED`	101	Canceled by user.
`CANNOT_AUTH`	35	The server does not support basic authentication.
`CIRCULAR_COMPONENT_DEPENDENCY`	64	Circular dynamic component dependency.
`COMPONENT_DEPS_LIMIT_EXCEEDED`	65	Dynamic component dependencies limit exceeded.
`COMPONENT_NAMESPACE_COLLISION`	72	The namespace used by a component is the same as another.
`CONTENT_HANDLER_CONFLICT`	55	The installation of a content handler would conflict with an already installed handler.
`CORRUPT_DEPENDENCY_HASH`	71	A dependency has a corrupt hash code.
`CORRUPT_JAR`	36	An entry could not be read from the JAR.
`CORRUPT_PROVIDER_CERT`	5	The content provider certificate cannot be decoded.
`CORRUPT_SIGNATURE`	8	The JAR signature cannot be decoded.
`DEVICE_INCOMPATIBLE`	40	The device does not support either the configuration or profile in the JAD.
`DUPLICATED_KEY`	88	Duplicated JAD/manifest key attribute
`EXPIRED_CA_KEY`	12	The certificate authority's public key has expired.
`EXPIRED_PROVIDER_CERT`	11	The content provider certificate has expired.
`INCORRECT_FONT_LOADING`	82	A font that is contained with the JAR cannot be loaded.
`INSUFFICIENT_STORAGE`	30	Not enough storage for this suite to be installed.
`INVALID_CONTENT_HANDLER`	54	The `MicroEdition-Handler-`<n> JAD attribute has invalid values.
`INVALID_JAD_TYPE`	37	The server did not have a resource with the correct type or the JAD downloaded has the wrong media type.
`INVALID_JAD_URL`	43	The JAD URL is invalid.
`INVALID_JAR_TYPE`	38	The server did not have a resource with the correct type or the JAR downloaded has the wrong media type.
`INVALID_JAR_URL`	44	The JAR URL is invalid.
`INVALID_KEY`	28	A key for an attribute is not formatted correctly.
`INVALID_NATIVE_LIBRARY`	85	A native library contained within the JAR cannot be loaded.
`INVALID_PACKAGING`	87	A dependency cannot be satisfied.
`INVALID_PAYMENT_INFO`	58	Indicates that the payment information provided with the IMlet suite is incomplete or incorrect.
`INVALID_PROVIDER_CERT`	7	The signature of the content provider certificate is invalid.
`INVALID_RMS_DATA_TYPE`	76	The server did not have a resource with the correct type or the JAD downloaded has the wrong media type.
`INVALID_RMS_DATA_URL`	73	The RMS data file URL is invalid.
`INVALID_SERVICE_EXPORT`	86	A LIBlet that exports a service with a LIBlet Services attribute does not contain the matching service provider configuration information.
`INVALID_SIGNATURE`	9	The signature of the JAR is invalid.
`INVALID_VALUE`	29	A value for an attribute is not formatted correctly.
`INVALID_VERSION`	16	The format of the version is invalid.
`IO_ERROR`	102	A low-level hardware error has occurred.
`JAD_MOVED`	34	The JAD URL for an installed suite is different than the original JAD URL.
`JAD_NOT_FOUND`	2	The JAD was not found.
`JAD_SERVER_NOT_FOUND`	1	The server for the JAD was not found.
`JAR_CLASSES_VERIFICATION_FAILED`	56	Not all classes within JAR package can be successfully verified with class verifier.
`JAR_IS_LOCKED`	100	Component or MIDlet or IMlet suite is locked by the system.
`JAR_NOT_FOUND`	20	The JAR was not found at the URL given in the JAD.
`JAR_SERVER_NOT_FOUND`	19	The server for the JAR was not found at the URL given in the JAD.
`JAR_SIZE_MISMATCH`	31	The JAR downloaded was not the same size as given in the JAD.
`MISSING_CONFIGURATION`	41	The configuration is missing from the manifest.
`MISSING_DEPENDENCY_HASH`	67	A dependency hash code is missing.
`MISSING_DEPENDENCY_JAD_URL`	66	A dependency JAD URL is missing.
`MISSING_JAR_SIZE`	21	The JAR size is missing.
`MISSING_JAR_URL`	18	The URL for the JAR is missing.
`MISSING_PROFILE`	42	The profile is missing from the manifest.
`MISSING_PROVIDER_CERT`	4	The content provider certificate is missing.
`MISSING_SUITE_NAME`	13	The name of MIDlet or IMlet suite is missing.
`MISSING_VENDOR`	14	The vendor is missing.
`MISSING_VERSION`	15	The version is missing.
`NEW_VERSION`	32	This suite is newer that the one currently installed.
`NO_ERROR`	0	No error.
`NOT_YET_VALID_PROVIDER_CERT`	89	A certificate is not yet valid.
`NOT_YET_VALID_CA_KEY`	90	A CA's public key is not yet valid.
`OLD_VERSION`	17	This suite is older that the one currently installed.
`OTHER_ERROR`	103	Other errors.
`PROXY_AUTH`	51	Indicates that the user must first authenticate with the proxy.
`PUSH_CLASS_FAILURE`	48	The class in a push attribute is not in `MIDlet-`<n> attribute.
`PUSH_DUP_FAILURE`	45	The connection in a push entry is already taken.
`PUSH_FORMAT_FAILURE`	46	The format of a push attribute has an invalid format.
`PUSH_PROTO_FAILURE`	47	The connection in a push attribute is not supported.
`REVOKED_CERT`	62	The certificate has been revoked.
`RMS_DATA_DECRYPT_PASSWORD`	83	Indicates that a password is required to decrypt RMS data.
`RMS_DATA_ENCRYPT_PASSWORD`	84	Indicates that a password is required to encrypt RMS data.
`RMS_DATA_NOT_FOUND`	75	The RMS data file was not found at the specified URL.
`RMS_DATA_SERVER_NOT_FOUND`	74	The server for the RMS data file was not found at the specified URL.
`RMS_INITIALIZATION_FAILURE`	81	Failure to import RMS data.
`SUITE_NAME_MISMATCH`	25	The MIDlet or IMlet suite name does not match the one in the JAR manifest.
`TOO_MANY_PROPS`	53	Indicates that either the JAD or manifest has too many properties to fit into memory.
`TRUSTED_OVERWRITE_FAILURE`	52	Indicates that the user tried to overwrite a trusted suite with an untrusted suite during an update.
`UNAUTHORIZED`	33	Web server authentication failed or is required.
`UNKNOWN_CA`	6	The certificate authority (CA) that issued the content provider certificate is unknown.
`UNKNOWN_CERT_STATUS`	63	The certificate is unknown to OCSP server.
`UNSUPPORTED_CERT`	10	The content provider certificate has an unsupported version.
`UNSUPPORTED_CHAR_ENCODING`	61	Indicates that the character encoding specified in the MIME type is not supported.
`UNSUPPORTED_PAYMENT_INFO`	57	Indicates that the payment information provided with the MIDlet or IMlet suite is incompatible with the current implementation.
`UNTRUSTED_PAYMENT_SUITE`	59	Indicates that the MIDlet or IMlet suite has payment provisioning information but it is not trusted.
`VENDOR_MISMATCH`	27	The vendor does not match the one in the JAR manifest.
`VERSION_MISMATCH`	26	The version does not match the one in the JAR manifest.