Package com.yahoo.jdisc.application

Interface OsgiFramework

  • All Known Implementing Classes:
    FelixFramework, NonWorkingOsgiFramework
    public interface OsgiFramework
    This is an abstraction of the OSGi framework that hides the actual implementation details. If you need access to this interface, simply inject it into your Application. In most cases, however, you are better of injecting a BundleInstaller since that provides common convenience methods.
    Author:
    Simon Thoresen Hult, gjoranv

    • Method Summary

      All Methods Instance Methods Abstract Methods Default Methods 
      Modifier and Type Method Description
      void allowDuplicateBundles​(java.util.Collection<org.osgi.framework.Bundle> bundles)
      Allows this framework to install duplicates of the given collection of bundles.
      org.osgi.framework.BundleContext bundleContext()
      Returns the BundleContext of this framework's system bundle.
      java.util.List<org.osgi.framework.Bundle> bundles()
      Returns an iterable collection of all installed bundles.
      java.util.List<org.osgi.framework.Bundle> getBundles​(org.osgi.framework.Bundle requestingBundle)
      Returns all installed bundles that are visible to the requesting bundle.
      java.util.List<org.osgi.framework.Bundle> installBundle​(java.lang.String bundleLocation)
      Installs a bundle from the specified location.
      default boolean isFelixFramework()
      Returns true if this is a Felix based framework and not e.g.
      void refreshPackages()
      Synchronously refresh all bundles currently loaded.
      void start()
      This method starts the framework instance.
      void startBundles​(java.util.List<org.osgi.framework.Bundle> bundles, boolean privileged)
      Starts the given Bundles.
      void stop()
      Synchronously shut down the framework.

    • Method Detail

      • installBundle

        java.util.List<org.osgi.framework.Bundle> installBundle​(java.lang.String bundleLocation)
                                                 throws org.osgi.framework.BundleException

        Installs a bundle from the specified location. The specified location identifier will be used as the identity of the bundle. If a bundle containing the same location identifier is already installed, the Bundle object for that bundle is returned. All bundles listed in the OsgiHeader.PREINSTALL_BUNDLE manifest header are also installed. The bundle at index 0 of the returned list matches the bundleLocation argument.

        NOTE: When this method installs more than one bundle, AND one of those bundles throw an exception during installation, the bundles installed prior to throwing the exception will remain installed. To enable the caller to recover from such a situation, this method wraps any thrown exception within a BundleInstallationException that contains the list of successfully installed bundles.

        It would be preferable if this method was exception-safe (that it would roll-back all installed bundles in the case of an exception), but that can not be implemented thread-safely since an Application may choose to install bundles concurrently through any available BundleContext.

        Parameters:
        bundleLocation - the location identifier of the bundle to install
        Returns:
        the list of Bundle objects installed, the object at index 0 matches the given location
        Throws:
        BundleInstallationException - if the input stream cannot be read, or the installation of a bundle failed, or the caller does not have the appropriate permissions, or the system BundleContext is no longer valid
        org.osgi.framework.BundleException

      • startBundles

        void startBundles​(java.util.List<org.osgi.framework.Bundle> bundles,
                  boolean privileged)
           throws org.osgi.framework.BundleException
        Starts the given Bundles. The parameter privileged tells the framework whether or not privileges are available, and is checked against the OsgiHeader.PRIVILEGED_ACTIVATOR header of each Bundle being started. Any bundle that is a fragment is silently ignored.
        Parameters:
        bundles - the bundles to start
        privileged - whether or not privileges are available
        Throws:
        org.osgi.framework.BundleException - if a bundle could not be started. This could be because a code dependency could not be resolved or the specified BundleActivator could not be loaded or threw an exception.
        java.lang.SecurityException - if the caller does not have the appropriate permissions
        java.lang.IllegalStateException - if this bundle has been uninstalled or this bundle tries to change its own state

      • refreshPackages

        void refreshPackages()
        Synchronously refresh all bundles currently loaded. Once this method returns, the class loaders of all bundles will reflect on the current set of loaded bundles. NOTE: This method is no longer used by the Jdisc container framework, but kept for completeness.

      • bundleContext

        org.osgi.framework.BundleContext bundleContext()
        Returns the BundleContext of this framework's system bundle. The returned BundleContext can be used by the caller to act on behalf of this bundle. This method may return null if it has no valid BundleContext.
        Returns:
        a BundleContext for the system bundle, or null
        Throws:
        java.lang.SecurityException - if the caller does not have the appropriate permissions

      • bundles

        java.util.List<org.osgi.framework.Bundle> bundles()
        Returns an iterable collection of all installed bundles. This method returns a list of all bundles installed in the OSGi environment at the time of the call to this method. However, since the OsgiFramework is a very dynamic environment, bundles can be installed or uninstalled at anytime.
        Returns:
        an iterable collection of Bundle objects, one object per installed bundle

      • getBundles

        java.util.List<org.osgi.framework.Bundle> getBundles​(org.osgi.framework.Bundle requestingBundle)
        Returns all installed bundles that are visible to the requesting bundle. Bundle visibility is controlled via implementations of FindHook;

      • allowDuplicateBundles

        void allowDuplicateBundles​(java.util.Collection<org.osgi.framework.Bundle> bundles)
        Allows this framework to install duplicates of the given collection of bundles. Duplicate detection is handled by the BundleCollisionHook.
        Parameters:
        bundles - The bundles to allow duplicates of

      • start

        void start()
    throws org.osgi.framework.BundleException
        This method starts the framework instance. Before this method is called, any call to installBundle(String) or bundles() will generate a NullPointerException.
        Throws:
        org.osgi.framework.BundleException - if any error occurs

      • stop

        void stop()
   throws org.osgi.framework.BundleException
        Synchronously shut down the framework. It must be called at the end of a session to shutdown all active bundles.
        Throws:
        org.osgi.framework.BundleException - if any error occurs

      • isFelixFramework

        default boolean isFelixFramework()
        Returns true if this is a Felix based framework and not e.g. a test framework.