Package org.codice.ddf.sync.installer.api

Interface SynchronizedInstaller

public interface SynchronizedInstaller
Performs various installations/configuration related operations and waits for expected states to be met before returning. WARNING: This service should be used with extreme caution. OSGI is a highly async framework, manually waiting for other bundle/service states to be met is typically a sign of a code smell or poor design. This service is primarily useful for determining when the system is in a ready state for users to interact with or testing.

This code is experimental. While this interface is functional and tested, it may change or * be removed in a future version of the library.

  • Method Summary

    Modifier and Type
    Method
    Description
    org.osgi.service.cm.Configuration
    createManagedFactoryService(long maxWaitTime, String factoryPid, Map<String,Object> properties, String bundleLocation)
    Creates a Managed Service using the Managed Service Factory matching the provided factory pid.
    org.osgi.service.cm.Configuration
    createManagedFactoryService(String factoryPid, Map<String,Object> properties, String bundleLocation)
    Creates a Managed Service using the Managed Service Factory matching the provided factory pid.
    void
    installFeatures(long maxWaitTime, EnumSet<org.apache.karaf.features.FeaturesService.Option> options, String feature, String... additionalFeatures)
    Installs and starts one or more features.
    void
    installFeatures(String feature, String... additionalFeatures)
    Installs and starts one or more features.
    void
    installFeatures(EnumSet<org.apache.karaf.features.FeaturesService.Option> options, String feature, String... additionalFeatures)
    Installs and starts one or more features.
    void
    startBundles(String symbolicName, String... additionalSymbolicNames)
    Starts the specified bundles.
    void
    stopBundles(String symbolicName, String... additionalSymbolicNames)
    Stops the specified bundles.
    void
    uninstallFeatures(long maxWaitTime, EnumSet<org.apache.karaf.features.FeaturesService.Option> options, String feature, String... additionalFeatures)
    Uninstalls one or more features.
    void
    uninstallFeatures(String feature, String... additionalFeatures)
    Uninstalls one or more features.
    void
    uninstallFeatures(EnumSet<org.apache.karaf.features.FeaturesService.Option> options, String feature, String... additionalFeatures)
    Uninstalls one or more features.
    void
    updateManagedService(long maxWaitTime, String servicePid, Map<String,Object> properties, String bundleLocation)
    Waits for Managed Service to come up before updating it's properties.
    void
    updateManagedService(String servicePid, Map<String,Object> properties, String bundleLocation)
    Waits for Managed Service to come up before updating its properties.
    void
    waitForBootFinish()
    Waits up to 10 minutes for the system to reach a state that is ready for user operation.
    void
    waitForBootFinish(long maxWaitTime)
    Waits for boot features to be installed and all bundles to reach an Active state
    void
    waitForBundles(long maxWaitTime, String... symbolicNames)
    Waits for installed bundles with the specified symbolic names to be in an Active before returning.
    void
    waitForBundles(String... symbolicNames)
    Waits for installed bundles with the specified symbolic names to be in an Active before returning.
    void
    waitForServiceToBeAvailable(long maxWaitTime, String servicePid)
    Waits for a service with a matching service pid to appear before returning.
    void
    waitForServiceToBeAvailable(String servicePid)
    Waits for a service with a matching service pid to appear before returning.

  • Method Details

    • waitForBootFinish

      void waitForBootFinish() throws InterruptedException
      Waits up to 10 minutes for the system to reach a state that is ready for user operation.
      Throws:
      SynchronizedInstallerException - if an error occurs while performing wait
      SynchronizedInstallerTimeoutException - if condition takes longer than max wait time to be met
      InterruptedException - if thread is interrupted while waiting for condition to be met

    • waitForBootFinish

      void waitForBootFinish(long maxWaitTime) throws InterruptedException
      Waits for boot features to be installed and all bundles to reach an Active state
      Parameters:
      maxWaitTime - max period to wait, in milliseconds, for boot to finish before failing
      Throws:
      SynchronizedInstallerException - if an error occurs while performing wait
      SynchronizedInstallerTimeoutException - if condition takes longer than max wait time to be met
      InterruptedException - if thread is interrupted while waiting for condition to be met

    • createManagedFactoryService

      org.osgi.service.cm.Configuration createManagedFactoryService(String factoryPid, @Nullable Map<String,Object> properties, @Nullable String bundleLocation) throws InterruptedException
      Creates a Managed Service using the Managed Service Factory matching the provided factory pid. Waits for the service to be registered before returning For Managed Services not created from a Managed Service Factory, use updateManagedService(String, Map, String) instead.
      Parameters:
      factoryPid - the factory pid of the Managed Service Factory
      properties - the service properties for the Managed Service
      bundleLocation - the bundle location the configuration should be associated with. See Configuration.getBundleLocation() for more details.
      Returns:
      configuration of the service created
      Throws:
      SynchronizedInstallerException - if an error occurs while performing wait
      SynchronizedInstallerTimeoutException - if condition takes longer than max wait time to be met
      InterruptedException - if thread is interrupted while waiting for condition to be met

    • createManagedFactoryService

      org.osgi.service.cm.Configuration createManagedFactoryService(long maxWaitTime, String factoryPid, @Nullable Map<String,Object> properties, @Nullable String bundleLocation) throws InterruptedException
      Creates a Managed Service using the Managed Service Factory matching the provided factory pid. Waits for the service to be registered before returning For Managed Services not created from a Managed Service Factory, use updateManagedService(String, Map, String) instead.
      Parameters:
      maxWaitTime - the max time to wait, in milliseconds, for the service to appear before failing
      factoryPid - the factory pid of the Managed Service Factory
      properties - the service properties for the Managed Service
      bundleLocation - the bundle location the configuration should be associated with. See Configuration.getBundleLocation() for more details.
      Returns:
      configuration of the service created
      Throws:
      SynchronizedInstallerException - if an error occurs while performing wait
      SynchronizedInstallerTimeoutException - if condition takes longer than max wait time to be met
      InterruptedException - if thread is interrupted while waiting for condition to be met

    • updateManagedService

      void updateManagedService(String servicePid, Map<String,Object> properties, @Nullable String bundleLocation) throws InterruptedException
      Waits for Managed Service to come up before updating its properties. Waits for the properties to be reflected in the service's Configuration. Does not guarantee the bean has received the values from the Configuration. For services created from a Managed Service Factory, use createManagedFactoryService(String, Map, String) instead.
      Parameters:
      servicePid - persistent identifier of the Managed Service to update
      properties - service configuration properties
      bundleLocation - the bundle location the configuration should be associated with. See Configuration.getBundleLocation() for more details.
      Throws:
      SynchronizedInstallerException - if an error occurs while performing wait
      SynchronizedInstallerTimeoutException - if condition takes longer than max wait time to be met
      InterruptedException - if thread is interrupted while waiting for condition to be met

    • updateManagedService

      void updateManagedService(long maxWaitTime, String servicePid, Map<String,Object> properties, @Nullable String bundleLocation) throws InterruptedException
      Waits for Managed Service to come up before updating it's properties. Waits for the properties to reflected in the services Configuration. Does not guarantee the bean has received the values from the Configuration. For services created from a Managed Service Factory, use createManagedFactoryService(String, Map, String) instead.
      Parameters:
      maxWaitTime - the max time to wait, in milliseconds, for the service to appear invalid input: '&' changes to be reflected in service configuration before failing
      servicePid - persistent identifier of the Managed Service to start
      properties - service configuration properties
      bundleLocation - the bundle location the configuration should be associated with. See Configuration.getBundleLocation() for more details.
      Throws:
      SynchronizedInstallerException - if an error occurs while performing wait
      SynchronizedInstallerTimeoutException - if condition takes longer than max wait time to be met
      InterruptedException - if thread is interrupted while waiting for condition to be met

    • waitForServiceToBeAvailable

      void waitForServiceToBeAvailable(String servicePid) throws InterruptedException
      Waits for a service with a matching service pid to appear before returning.
      Parameters:
      servicePid - persistent identifier of the Managed Service to wait for
      Throws:
      SynchronizedInstallerException - if an error occurs while performing wait
      SynchronizedInstallerTimeoutException - if condition takes longer than max wait time to be met
      InterruptedException - if thread is interrupted while waiting for condition to be met

    • waitForServiceToBeAvailable

      void waitForServiceToBeAvailable(long maxWaitTime, String servicePid) throws InterruptedException
      Waits for a service with a matching service pid to appear before returning.
      Parameters:
      maxWaitTime - the max time, in milliseconds, to wait for the service to appear before failing
      servicePid - persistent identifier of the Managed Service to wait for
      Throws:
      SynchronizedInstallerException - if an error occurs while performing wait
      SynchronizedInstallerTimeoutException - if condition takes longer than max wait time to be met
      InterruptedException - if thread is interrupted while waiting for condition to be met

    • installFeatures

      void installFeatures(String feature, String... additionalFeatures) throws InterruptedException
      Installs and starts one or more features. Waits until the state of all specified features are Started and all bundles are Active before returning.
      Parameters:
      feature - name of feature to be started
      additionalFeatures - names of additional features to be started
      Throws:
      SynchronizedInstallerException - if an error occurs while performing wait
      SynchronizedInstallerTimeoutException - if condition takes longer than max wait time to be met
      InterruptedException - if thread is interrupted while waiting for condition to be met

    • installFeatures

      void installFeatures(EnumSet<org.apache.karaf.features.FeaturesService.Option> options, String feature, String... additionalFeatures) throws InterruptedException
      Installs and starts one or more features. Waits until the state of all specified features are Started and all bundles are Active before returning.
      Parameters:
      options - additional feature installation options
      feature - name of feature to be started
      additionalFeatures - names of additional features to be started
      Throws:
      SynchronizedInstallerException - if an error occurs while performing wait
      SynchronizedInstallerTimeoutException - if condition takes longer than max wait time to be met
      InterruptedException - if thread is interrupted while waiting for condition to be met

    • installFeatures

      void installFeatures(long maxWaitTime, EnumSet<org.apache.karaf.features.FeaturesService.Option> options, String feature, String... additionalFeatures) throws InterruptedException
      Installs and starts one or more features. Waits until the state of all specified features are Started and all bundles are Active before returning.
      Parameters:
      maxWaitTime - the max wait time, in milliseconds, for features to start and bundles to reach an Active state
      options - additional feature installation options
      feature - name of feature to be started
      additionalFeatures - names of additional features to be started
      Throws:
      SynchronizedInstallerException - if an error occurs while performing wait
      SynchronizedInstallerTimeoutException - if condition takes longer than max wait time to be met
      InterruptedException - if thread is interrupted while waiting for condition to be met

    • uninstallFeatures

      void uninstallFeatures(String feature, String... additionalFeatures) throws InterruptedException
      Uninstalls one or more features. Waits for the all bundles to reach an Active state before returning
      Parameters:
      feature - name of feature to uninstall
      additionalFeatures - names of additional features to uninstall
      Throws:
      SynchronizedInstallerException - if an error occurs while performing wait
      SynchronizedInstallerTimeoutException - if condition takes longer than max wait time to be met
      InterruptedException - if thread is interrupted while waiting for condition to be met

    • uninstallFeatures

      void uninstallFeatures(EnumSet<org.apache.karaf.features.FeaturesService.Option> options, String feature, String... additionalFeatures) throws InterruptedException
      Uninstalls one or more features. Waits for the all bundles to reach an Active state before returning
      Parameters:
      options - additional options for feature uninstalls
      feature - name of feature to uninstall
      additionalFeatures - names of additional features to uninstall
      Throws:
      SynchronizedInstallerException - if an error occurs while performing wait
      SynchronizedInstallerTimeoutException - if condition takes longer than max wait time to be met
      InterruptedException - if thread is interrupted while waiting for condition to be met

    • uninstallFeatures

      void uninstallFeatures(long maxWaitTime, EnumSet<org.apache.karaf.features.FeaturesService.Option> options, String feature, String... additionalFeatures) throws InterruptedException
      Uninstalls one or more features. Waits until all bundles reach an Active state before returning.
      Parameters:
      maxWaitTime - the max wait time, in milliseconds, for features to start and bundles to reach an Active state
      options - additional options for feature uninstalls
      feature - name of feature to be started
      additionalFeatures - names of additional features to be started
      Throws:
      SynchronizedInstallerException - if an error occurs while performing wait
      SynchronizedInstallerTimeoutException - if condition takes longer than max wait time to be met
      InterruptedException - if thread is interrupted while waiting for condition to be met

    • stopBundles

      void stopBundles(String symbolicName, String... additionalSymbolicNames)
      Stops the specified bundles.
      Parameters:
      symbolicName - symbolic name of installed bundle to stop
      additionalSymbolicNames - symbolic names of additional installed bundles to stop
      Throws:
      SynchronizedInstallerException - if an error occurs while stopping bundles

    • startBundles

      void startBundles(String symbolicName, String... additionalSymbolicNames)
      Starts the specified bundles. In the case of a fragment, the Resolved state waited for before returning.
      Parameters:
      symbolicName - symbolic name of installed bundle to start
      additionalSymbolicNames - symbolic names of additional installed bundles to start
      Throws:
      SynchronizedInstallerException - if an error occurs while starting bundles

    • waitForBundles

      void waitForBundles(String... symbolicNames) throws InterruptedException
      Waits for installed bundles with the specified symbolic names to be in an Active before returning. In the case of a fragment, the Resolved state waited for before returning. If no symbolicNames are specified, this method will wait for all installed bundles to reach an Active state before returning.
      Parameters:
      symbolicNames - symbolic names of installed bundles to wait to reach an Active state
      Throws:
      SynchronizedInstallerException - if an error occurs while performing wait
      SynchronizedInstallerTimeoutException - if condition takes longer than max wait time to be met
      InterruptedException - if thread is interrupted while waiting for condition to be met

    • waitForBundles

      void waitForBundles(long maxWaitTime, String... symbolicNames) throws InterruptedException
      Waits for installed bundles with the specified symbolic names to be in an Active before returning. In the case of a fragment, the Resolved state waited for before returning. If no symbolicNames are specified, this method will wait for all installed bundles to reach an Active state before returning.
      Parameters:
      maxWaitTime - max time to wait, in milliseconds, for bundles to reach an Active state
      symbolicNames - symbolic names of installed bundles to wait to reach an Active state
      Throws:
      SynchronizedInstallerException - if an error occurs while performing wait
      SynchronizedInstallerTimeoutException - if condition takes longer than max wait time to be met
      InterruptedException - if thread is interrupted while waiting for condition to be met