org.ocap.system.RegisteredApiManager.html Maven / Gradle / Ivy

This class represents a manager for registered APIs that can be registered with an implementation by a privileged application.

RegisteredApiManager

protected RegisteredApiManager()

Protected constructor.

getInstance

public static RegisteredApiManager getInstance()

Gets the singleton instance of the Registered API manager.

Returns:

The Registered API manager.

register

public abstract void register(java.lang.String name,
                              java.lang.String version,
                              java.io.File scdf,
                              short storagePriority)
                       throws java.io.IOException

Registers an API with the implementation.

If the name and version number matches an API already registered, this function does nothing (successfully). Matches for both name and version are based on exact case sensitive comparisons.

If the name matches an API already registered, and the version number is different, the implementation SHALL: remove the existing API before installing the new API. The removal SHALL obey the semantics specified for the unregister() method. If the installation fails then the previously registered API SHALL NOT be removed. The removal of the previous API and installation of the new API SHALL be one atomic operation. (Note: This implies that the terminal MUST download and authenticate all files required for the new API, and only if this succeeds can it then remove the old API & install the new API. Application authors that do not need this behavior should note that unregistering the old API before registering a new version may reduce the memory usage of this operation and is strongly recommended).

Paths in the SCDF are relative to the directory containing the SCDF. The priority field specified in the SCDF is ignored.

Parameters:

name - Name of the registered API.

version - Version of the registered API.

scdf - Path to the shared classes descriptor file.

storagePriority - Storage priority of classes in the SCDF.

Throws:

java.lang.IllegalArgumentException - if storagePriority is not a valid value as defined in chapter 12.

java.lang.IllegalStateException - if the API to be updated is in use by any application.

java.io.IOException - if the SCDF or any file listed in it does not exist, cannot be loaded, or are not correctly signed. Also thrown if the SCDF is not the correct format and cannot be parsed.

java.lang.SecurityException - if the calling application does not have MonitorAppPermission("registeredapi.manager").

unregister

public abstract void unregister(java.lang.String name)

Unregisters an API from the implementation. Removes all of the shared class files associated with the registered API from persistent and volatile memory. Removes the registered API from the registered API list.

Parameters:

name - Name of the registered API to unregister.

Throws:

java.lang.IllegalArgumentException - if no registered API with the name parameter has been registered.

java.lang.IllegalStateException - if the API to be unregistered is in use by any application.

java.lang.SecurityException - if the calling application does not have MonitorAppPermission("registeredapi.manager").

getNames

public abstract java.lang.String[] getNames()

Gets a list of registered APIs. Note that this is intended for use by applications that manage registered APIs. Applications that use a registered API should call getUsedNames().

Returns:

An array of registered API names.

Throws:

java.lang.SecurityException - if the calling application does not have MonitorAppPermission("registeredapi.manager").

getVersion

public abstract java.lang.String getVersion(java.lang.String name)

Gets the version of a registered API, or null if it is not registered.

Parameters:

name - the name of the registered API.

Returns:

the version of the registered API, or null if it is not registered.

Throws:

java.lang.SecurityException - if the calling application does not have MonitorAppPermission("registeredapi.manager") or RegisteredApiUserPermission(name).

getUsedNames

public abstract java.lang.String[] getUsedNames()

Gets a list of registered APIs that are in use by the caller.

Returns:

An array of registered API names that are in use by the caller.