| java.lang.Object
 com.sun.midp.installer.Installer
All known Subclasses: com.sun.midp.installer.HttpInstaller, com.sun.midp.installer.FileInstaller,
| Installer | | abstract public class Installer (Code) | | An Installer manages MIDlet suites and libraries
present in a Java application environment. An MIDlet suite
distributed as a descriptor and JAR pair.
The descriptor identifies the configuration and contains security
information and the manifest of the JAR describes the contents.
The implementation of an Installer is
specific to the platform and provides access to
procedures that make an MIDlet suite visible to users.
Each installed package is uniquely identified by a storage name
constructed from the combination
of the values of the MIDlet-Name and
MIDlet-Vendor attributes.
The syntax and content of the strings used to identify
installed packages are implementation dependent.
Only packages installed or upgraded using this API appear
in the list of known packages.
|
| Constructor Summary | |
| | Installer()
Constructor of the Installer. |
| Method Summary | |
| protected void | checkForDifferentDomains(String url)
If the JAD belongs to an installed suite, check the URL against the
installed one. | | protected void | checkForJadManifestMismatches()
Checks to see that if any properties that are both in the JAD and
JAR manifest are not equal and throw a exception and notify the
server when a mismatch is found. | | protected void | checkPreviousVersion()
See if there is an installed version of the suite being installed and
if so, make an necessary checks. | | abstract protected byte[] | downloadJAD()
Downloads an application descriptor file from the given URL. | | abstract protected int | downloadJAR(String filename)
Downloads an application archive file from the given URL into the
given file. | | protected byte[] | getInitialPermissions(String domain)
Builds the initial API permission for suite currently being installed. | | protected InstallStateImpl | getInstallState()
Creates an instance of InstallState of the appropriate type
depending on the installer type. | | public static String | getUrlPath(String url)
Retrieves a path component of the given URL. | | public static String | getUrlScheme(String url, String defaultScheme)
Retrieves a scheme component of the given URL. | | public int | installJad(String location, int storageId, boolean force, boolean removeRMS, InstallListener installListener)
Installs a software package from the given URL. | | public int | installJar(String location, String name, int storageId, boolean force, boolean removeRMS, InstallListener installListener)
Installs a software package from the given URL. | | public boolean | isJadSigned()
Checks to see if the JAD has a signature, but does not verify the
signature. | | abstract protected boolean | isSameUrl(String url1, String url2)
Compares two URLs for equality in sense that they have the same
scheme, host and path. | | protected int | performInstall()
Performs an install. | | protected void | postInstallMsgBackToProvider(String message)
Posts a status message back to the provider's URL in JAD. | | protected void | processPreviousRMS()
If this is an update, make sure the RMS data is handle correctly
according to the OTA spec. | | public void | setExtraPermissions(String extraPermissions)
Sets the permissions that must be allowed not depending on their
presence in the application descriptor file. | | public void | setUnsignedSecurityDomain(String domain)
Sets security domain for unsigned suites. | | public boolean | stopInstalling()
Stops the installation. | | protected int | transferData(InputStream in, OutputStream out, int chunkSize)
Function that actually does the work of transferring file data.
Updates the listener every 1 K bytes.
If the amount of data to be read is larger than maxDLSize
we will break the input into chunks no larger than
chunkSize. | | public void | verifyMIDlet(String classname)
Verify that a class is present in the JAR file. | | public boolean | wasStopped()
Tells if the installation was stopped by another thread. |
| CORRUPTED_SUITE | | final public static int CORRUPTED_SUITE(Code) | | Status code for corrupted suite
|
| DOWNLOADED_1K_OF_JAD | | final public static int DOWNLOADED_1K_OF_JAD(Code) | | Status code to signal that another 1K of the JAD has been download.
|
| DOWNLOADED_1K_OF_JAR | | final public static int DOWNLOADED_1K_OF_JAR(Code) | | Status code to signal that another 1K of the JAR has been download.
|
| DOWNLOADING_JAD | | final public static int DOWNLOADING_JAD(Code) | | Status code to signal connection to the JAD server was successful.
|
| DOWNLOADING_JAR | | final public static int DOWNLOADING_JAR(Code) | | Status code to signal connection to the JAR server was successful.
|
| GENERATING_APP_IMAGE | | final public static int GENERATING_APP_IMAGE(Code) | | Status code to signal that application image is being generating.
|
| JAD_MT | | final public static String JAD_MT(Code) | | Media-Type for valid application descriptor files.
|
| JAR_MT_1 | | final public static String JAR_MT_1(Code) | | Media-Type for valid Jar file.
|
| JAR_MT_2 | | final public static String JAR_MT_2(Code) | | Media-Type for valid Jar file.
|
| MICROEDITION_CONFIG | | final protected static String MICROEDITION_CONFIG(Code) | | System property containing the microedition configuration
|
| MICROEDITION_LOCALE | | final protected static String MICROEDITION_LOCALE(Code) | | System property containing the microedition locale
|
| MICROEDITION_PROFILES | | final protected static String MICROEDITION_PROFILES(Code) | | System property containing the supported microedition profiles
|
| STORING_SUITE | | final public static int STORING_SUITE(Code) | | Status code for local writing of the verified MIDlet suite.
Stopping the install at this point has no effect, so there user
should not be given a chance to stop the install.
|
| TMP_FILENAME | | final protected static String TMP_FILENAME(Code) | | Filename to save the JAR of the suite temporarily. This is used
to avoid overwriting an existing JAR prior to verification.
|
| VERIFYING_SUITE | | final public static int VERIFYING_SUITE(Code) | | Status code to signal that download is done and the suite is being
verified.
|
| VERIFYING_SUITE_CLASSES | | final public static int VERIFYING_SUITE_CLASSES(Code) | | Status code to signal that suite classes are being verified.
|
| additionalPermissions | | protected String additionalPermissions(Code) | | Include this permissions into the list of permissions
given in MIDlet-Permissions jad attribute for unsigned
suites.
|
| cldcConfig | | protected String cldcConfig(Code) | | Holds the CLDC configuration string.
|
| cldcRuntimeEnv | | final protected String cldcRuntimeEnv(Code) | | Holds the device's Runtime Execution Environment string.
|
| info | | protected InstallInfo info(Code) | | An alias for more state.installInfo to get more compact record.
|
| settings | | protected SuiteSettings settings(Code) | | An alias for more state.suiteSettings to get more compact record.
|
| state | | protected InstallStateImpl state(Code) | | Holds the install state.
|
| unsignedSecurityDomain | | protected String unsignedSecurityDomain(Code) | | Use this to be the security domain for unsigned suites.
|
| verifier | | protected Verifier verifier(Code) | | Midlet suite signature verifier.
|
| Installer | | Installer()(Code) | | Constructor of the Installer.
|
| checkForDifferentDomains | | protected void checkForDifferentDomains(String url)(Code) | | If the JAD belongs to an installed suite, check the URL against the
installed one. Set the state.exception if the user needs to be warned.
Parameters:
url - JAD or JAR URL of the suite being installed |
| checkForJadManifestMismatches | | protected void checkForJadManifestMismatches() throws InvalidJadException(Code) | | Checks to see that if any properties that are both in the JAD and
JAR manifest are not equal and throw a exception and notify the
server when a mismatch is found. Only used for trusted suites.
exception:
InvalidJadException - if the properties do not match |
| downloadJAD | | abstract protected byte[] downloadJAD() throws IOException(Code) | | Downloads an application descriptor file from the given URL.
a byte array representation of the file or null if not found
exception:
IOException - is thrown if any error prevents the downloadof the JAD |
| downloadJAR | | abstract protected int downloadJAR(String filename) throws IOException(Code) | | Downloads an application archive file from the given URL into the
given file. Automatically handle re-tries.
Parameters:
filename - name of the file to write. This file residesin the storage area of the given application size of the JAR
exception:
IOException - is thrown if any error prevents the downloadof the JAR |
| getInitialPermissions | | protected byte[] getInitialPermissions(String domain) throws InvalidJadException(Code) | | Builds the initial API permission for suite currently being installed.
Parameters:
domain - security domain name for the CA of the suite current level of permissions
exception:
InvalidJadException - if a permission attribute is notformatted properly or a required permission is denied |
| getInstallState | | protected InstallStateImpl getInstallState()(Code) | | Creates an instance of InstallState of the appropriate type
depending on the installer type. Should be overloaded in the
inherited classes.
an instance of class containing the installation state |
| getUrlPath | | public static String getUrlPath(String url)(Code) | | Retrieves a path component of the given URL.
Parameters:
url - url to parse path component of the given URL |
| getUrlScheme | | public static String getUrlScheme(String url, String defaultScheme)(Code) | | Retrieves a scheme component of the given URL.
Parameters:
url - url to parse
Parameters:
defaultScheme - if the url has no scheme component, this onewill be returned; may be null scheme component of the given URL |
| installJad | | public int installJad(String location, int storageId, boolean force, boolean removeRMS, InstallListener installListener) throws IOException, InvalidJadException, MIDletSuiteLockedException, SecurityException(Code) | | Installs a software package from the given URL. The URL is assumed
refer to an application descriptor.
If the component to be installed is the same as an existing
component (by comparing the MIDlet-Name,
MIDlet-Vendor attributes)
then this install is an upgrade if the version number is greater
than the current version. If so, the new version replaces in its
entirety the current version.
It is implementation dependent when the upgraded component is
made available for use.
The implementation of install must be robust in the presence
of failures such as running out of memory. If this method
throws an exception then the package must not be installed
and any previous version of the component must be left intact
and operational.
To receive status updates and installer warnings, provide an install
listener. If no listener is provided all warnings will be thrown
as exceptions.
Parameters:
location - the URL from which the application descriptor can beupdated
Parameters:
storageId - ID of the storage where the suite should be saved
Parameters:
force - if true the MIDlet suite components to beinstalled will overwrite any existing components withoutany version comparison
Parameters:
removeRMS - if true and existing RMS data will beremoved when overwriting an existing suite
Parameters:
installListener - object to receive status updates and installwarnings, can be null the unique ID of the installed package.
exception:
ConnectionNotFoundException - if JAD URL is invalid
exception:
IOException - is thrown if any error prevents the installationof the MIDlet suite, including being unable to access the applicationdescriptor or JAR
exception:
InvalidJadException - if the downloaded application descriptoris invalid
exception:
MIDletSuiteLockedException - is thrown, if the MIDletSuite islocked
exception:
SecurityException - if the caller does not have permissionto install software
exception:
IllegalArgumentException - is thrown, if the location of thedescriptor file is not specified |
| installJar | | public int installJar(String location, String name, int storageId, boolean force, boolean removeRMS, InstallListener installListener) throws IOException, InvalidJadException, MIDletSuiteLockedException(Code) | | Installs a software package from the given URL. The URL is assumed
refer to a JAR.
If the component to be installed is the same as an existing
component (by comparing the MIDlet-Name,
MIDlet-Vendor attributes)
then this install is an upgrade if the version number is greater
than the current version. If so, the new version replaces in its
entirety the current version.
It is implementation dependent when the upgraded component is
made available for use.
The implementation of install must be robust in the presence
of failures such as running out of memory. If this method
throws an exception then the package must not be installed
and any previous version of the component must be left intact
and operational.
To receive status updates and installer warnings, provide an install
listener. If no listener is provided all warnings will be thrown
as exceptions.
Parameters:
location - the URL from which the JAR can be updated
Parameters:
name - the name of the suite to be updated
Parameters:
storageId - ID of the storage where the suite should be saved
Parameters:
force - if true the MIDlet suite components to beinstalled will overwrite any existing components withoutany version comparison
Parameters:
removeRMS - if true and existing RMS data will beremoved when overwriting an existing suite
Parameters:
installListener - object to receive status updates and installwarnings, can be null the unique ID of the installed package.
exception:
IOException - is thrown if any error prevents the installationof the MIDlet suite, including being unable to access the JAR
exception:
InvalidJadException - if the downloaded JAR is invalid
exception:
MIDletSuiteLockedException - is thrown, if the MIDletSuite islocked
exception:
SecurityException - if the caller does not have permissionto install software
exception:
IllegalArgumentException - is thrown, if the location of theJAR specified |
| isJadSigned | | public boolean isJadSigned()(Code) | | Checks to see if the JAD has a signature, but does not verify the
signature. This is a place holder the the Secure Installer and
just returns false.
true if the JAD has a signature |
| isSameUrl | | abstract protected boolean isSameUrl(String url1, String url2)(Code) | | Compares two URLs for equality in sense that they have the same
scheme, host and path.
Parameters:
url1 - the first URL for comparision
Parameters:
url1 - the second URL for comparision true if the scheme, host and path of the first given urlis identical to the scheme, host and path of the secondgiven url; false otherwise |
| postInstallMsgBackToProvider | | protected void postInstallMsgBackToProvider(String message)(Code) | | Posts a status message back to the provider's URL in JAD.
Parameters:
message - status message to post |
| processPreviousRMS | | protected void processPreviousRMS() throws IOException(Code) | | If this is an update, make sure the RMS data is handle correctly
according to the OTA spec.
From the OTA spec:
The RMS record stores of a MIDlet suite being updated MUST be
managed as follows:
-
If the cryptographic signer of the new MIDlet suite and the
original MIDlet suite are identical, then the RMS record
stores MUST be retained and made available to the new MIDlet
suite.
-
If the scheme, host, and path of the URL that the new
Application Descriptor is downloaded from is identical to the
scheme, host, and path of the URL the original Application
Descriptor was downloaded from, then the RMS MUST be retained
and made available to the new MIDlet suite.
-
If the scheme, host, and path of the URL that the new MIDlet
suite is downloaded from is identical to the scheme, host, and
path of the URL the original MIDlet suite was downloaded from,
then the RMS MUST be retained and made available to the new
MIDlet suite.
-
If the above statements are false, then the device MUST ask
the user whether the data from the original MIDlet suite
should be retained and made available to the new MIDlet
suite.
exception:
IOException - if the install is stopped |
| setExtraPermissions | | public void setExtraPermissions(String extraPermissions)(Code) | | Sets the permissions that must be allowed not depending on their
presence in the application descriptor file.
Can only be called by JAM for testing.
Parameters:
extraPermissions - list of permissions that must be allowed evenif they are absent from the jad file; "all" to allow all permissions |
| setUnsignedSecurityDomain | | public void setUnsignedSecurityDomain(String domain)(Code) | | Sets security domain for unsigned suites. The default is untrusted.
Can only be called by JAM for testing.
Parameters:
domain - name of a security domain
Parameters:
allowedPermissions - list of permissions that must be allowed evenif they are absent from the jad file; "all" to allow all permissions |
| stopInstalling | | public boolean stopInstalling()(Code) | | Stops the installation. If installer is not installing then this
method has no effect. This will cause the install method to
throw an IOException if the install is not writing the suite
to storage which is the point of no return.
true if the install will stop, false if it is too late |
| transferData | | protected int transferData(InputStream in, OutputStream out, int chunkSize) throws IOException(Code) | | Function that actually does the work of transferring file data.
Updates the listener every 1 K bytes.
If the amount of data to be read is larger than maxDLSize
we will break the input into chunks no larger than
chunkSize. This prevents the VM from running out of
memory when processing large files.
Parameters:
in - the input stream to read from
Parameters:
out - the output stream to write to
Parameters:
chunkSize - size of piece to read from the input buffer number of bytes written to the output stream
exception:
IOException - if any exceptions occur during transferof data |
| verifyMIDlet | | public void verifyMIDlet(String classname) throws InvalidJadException(Code) | | Verify that a class is present in the JAR file.
If the classname is invalid or is not found an
InvalidJadException is thrown.
Parameters:
classname - the name of the class to verify
exception:
InvalidJadException - is thrown if the name is null or emptyor if the file is not found |
| wasStopped | | public boolean wasStopped()(Code) | | Tells if the installation was stopped by another thread.
true if the installation was stopped by another thread |
|
|