1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
|
// Copyright Yahoo. Licensed under the terms of the Apache 2.0 license. See LICENSE in the project root.
package com.yahoo.jdisc.application;
import org.osgi.framework.Bundle;
import org.osgi.framework.BundleContext;
import org.osgi.framework.BundleException;
import java.util.Collection;
import java.util.List;
/**
* 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
* {@link BundleInstaller} since that provides common convenience methods.
*
* @author Simon Thoresen Hult
* @author gjoranv
*/
public interface OsgiFramework {
/**
* <p>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 <code>Bundle</code>
* object for that bundle is returned. All bundles listed in the {@link OsgiHeader#PREINSTALL_BUNDLE} manifest
* header are also installed. The bundle at index 0 of the returned list matches the <code>bundleLocation</code>
* argument.</p>
*
* <p><b>NOTE:</b> When this method installs more than one bundle, <em>AND</em> 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 {@link
* BundleInstallationException} that contains the list of successfully installed bundles.</p>
*
* <p>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 <code>Application</code> may choose to
* install bundles concurrently through any available <code>BundleContext</code>.</p>
*
* @param bundleLocation the location identifier of the bundle to install
* @return 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 {@link
* BundleContext} is no longer valid
*/
List<Bundle> installBundle(String bundleLocation) throws BundleException;
/**
* Starts the given {@link Bundle}s. The parameter <code>privileged</code> tells the framework whether or not
* privileges are available, and is checked against the {@link OsgiHeader#PRIVILEGED_ACTIVATOR} header of each
* Bundle being started. Any bundle that is a fragment is silently ignored.
*
* @param bundles the bundles to start
* @param privileged whether or not privileges are available
* @throws 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.
* @throws SecurityException if the caller does not have the appropriate permissions
* @throws IllegalStateException if this bundle has been uninstalled or this bundle tries to change its own state
*/
void startBundles(List<Bundle> bundles, boolean privileged) throws BundleException;
/**
* 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.
*/
void refreshPackages();
/**
* 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 <code>null</code> if it has no valid
* BundleContext.
*
* @return a <code>BundleContext</code> for the system bundle, or <code>null</code>
* @throws SecurityException if the caller does not have the appropriate permissions
*/
BundleContext bundleContext();
/**
* 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.
*
* @return an iterable collection of Bundle objects, one object per installed bundle
*/
List<Bundle> bundles();
/**
* Returns all installed bundles that are visible to the requesting bundle. Bundle visibility
* is controlled via implementations of {@link org.osgi.framework.hooks.bundle.FindHook};
*/
List<Bundle> getBundles(Bundle requestingBundle);
/**
* Allows this framework to install duplicates of the given collection of bundles. Duplicate detection
* is handled by the {@link com.yahoo.jdisc.core.BundleCollisionHook}.
*
* @param bundles The bundles to allow duplicates of. An empty collection will prohibit any duplicates.
*/
void allowDuplicateBundles(Collection<Bundle> bundles);
/**
* This method starts the framework instance. Before this method is called, any call to {@link
* #installBundle(String)} or {@link #bundles()} will generate a {@link NullPointerException}.
*
* @throws BundleException if any error occurs
*/
void start() throws BundleException;
/**
* Synchronously shut down the framework. It must be called at the end of a session to shutdown all active bundles.
*
* @throws BundleException if any error occurs
*/
void stop() throws BundleException;
/**
* Returns true if this is a Felix based framework and not e.g. a test framework.
*/
default boolean isFelixFramework() {
return false;
}
}
|
