RegisteredApiManager

Overview | Package | Class | Use | Tree | Deprecated | Index | Help

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.ocap.system
Class RegisteredApiManager

    java.lang.Object
      org.ocap.system.RegisteredApiManager

    public abstract class RegisteredApiManager

extends Object

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

Method Summary
`static RegisteredApiManager` | `getInstance()` Gets the singleton instance of the Registered API manager.
`abstract String[]` | `getNames()` Gets a list of registered APIs.
`abstract String[]` | `getUsedNames()` Gets a list of registered APIs that are in use by the caller.
`abstract String` | `getVersion(String name)` Gets the version of a registered API, or null if it is not registered.
`abstract void` | `register(String name, String version, File scdf, short storagePriority)` Registers an API with the implementation.
`abstract void` | `register(String name, String version, URL scdf, short storagePriority)` Registers an API with the implementation.
`abstract void` | `unregister(String name)` Unregisters an API from the implementation.

Methods inherited from class java.lang.Object
`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Method Detail

### getInstance

    public static RegisteredApiManager getInstance()

  Gets the singleton instance of the Registered API manager.

  Returns:
    The Registered API manager.

### register

    public abstract void register(String name,
                                  String version,
                                  File scdf,
                                  short storagePriority)
                           throws 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.

  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:
    `IllegalArgumentException` - if storagePriority is not a valid value as defined in chapter 12.
    `IllegalStateException` - if the API to be updated is in use by any application.
    `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.
    `SecurityException` - if the calling application does not have MonitorAppPermission("registeredapi.manager"). Also thrown if the caller does not have the necessary privileges to access the SCDF or listed files.

### register

    public abstract void register(String name,
                                  String version,
                                  URL scdf,
                                  short storagePriority)
                           throws 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 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 `URL` for the directory containing the SCDF.

  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:
    `IllegalArgumentException` - if storagePriority is not a valid value as defined in chapter 12.
    `IllegalStateException` - if the API to be updated is in use by any application.
    `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.
    `SecurityException` - if the calling application does not have MonitorAppPermission("registeredapi.manager"). Also thrown if the caller does not have the necessary privileges to access the SCDF or listed files.

### unregister

    public abstract void unregister(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:
    `IllegalArgumentException` - if no registered API with the name parameter has been registered.
    `IllegalStateException` - if the API to be unregistered is in use by any application.
    `SecurityException` - if the calling application does not have MonitorAppPermission("registeredapi.manager").

### getNames

    public abstract 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:
    `SecurityException` - if the calling application does not have MonitorAppPermission("registeredapi.manager").

### getVersion

    public abstract String getVersion(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:
    `SecurityException` - if the calling application does not have MonitorAppPermission("registeredapi.manager") or RegisteredApiUserPermission(name).

### getUsedNames

    public abstract 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.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD