1 package com.atlassian.plugin.osgi.container;
2
3 import org.osgi.framework.Bundle;
4 import org.osgi.framework.ServiceReference;
5 import org.osgi.util.tracker.ServiceTracker;
6
7 import java.io.File;
8 import java.util.List;
9
10 import com.atlassian.plugin.osgi.hostcomponents.HostComponentRegistration;
11 import org.osgi.util.tracker.ServiceTrackerCustomizer;
12
13 /**
14 * Manages the OSGi container and handles any interactions with it
15 */
16 public interface OsgiContainerManager
17 {
18 /**
19 * Starts the OSGi container
20 *
21 * @throws OsgiContainerException If the container cannot be started
22 */
23 void start() throws OsgiContainerException;
24
25 /**
26 * Stops the OSGi container
27 *
28 * @throws OsgiContainerException If the container cannot be stopped
29 */
30 void stop() throws OsgiContainerException;
31
32 /**
33 * Installs a bundle into a running OSGI container
34 * @param file The bundle file to install
35 * @return The created bundle
36 * @throws OsgiContainerException If the bundle cannot be loaded
37 */
38 Bundle installBundle(File file) throws OsgiContainerException;
39
40 /**
41 * @return If the container is running or not
42 */
43 boolean isRunning();
44
45 /**
46 * Gets a list of installed bundles
47 *
48 * @return An array of bundles
49 */
50 Bundle[] getBundles();
51
52 /**
53 * Gets a list of service references
54 * @return An array of service references
55 */
56 ServiceReference[] getRegisteredServices();
57
58 /**
59 * Gets a list of host component registrations
60 *
61 * @return A list of host component registrations
62 */
63 List<HostComponentRegistration> getHostComponentRegistrations();
64
65 /**
66 * Gets a service tracker to follow a service registered under a certain interface. Will return a new
67 * {@link ServiceTracker} instance for every call, so don't call more than necessary. Any provided
68 * {@link ServiceTracker} instances will be opened before returning and automatically closed on shutdown.
69 *
70 * @param interfaceClassName The interface class as a String
71 * @return A service tracker to follow all instances of that interface
72 * @throws IllegalStateException If the OSGi container is not running
73 * @since 2.1
74 */
75 ServiceTracker getServiceTracker(String interfaceClassName);
76
77 /**
78 * Gets a service tracker to follow a service registered under a certain interface with a
79 * {@link ServiceTrackerCustomizer} attached for customizing tracked service objects. Will return a new
80 * {@link ServiceTracker} instance for every call, so don't call more than necessary. Any provided
81 * {@link ServiceTracker} instances will be opened before returning and automatically closed on shutdown.
82 *
83 * @param interfaceClassName The interface class as a String
84 * @param serviceTrackerCustomizer service tracker customizer for the created service tracker
85 * @return A service tracker to follow all instances of that interface
86 * @throws IllegalStateException If the OSGi container is not running
87 * @since 2.13
88 */
89 ServiceTracker getServiceTracker(String interfaceClassName, ServiceTrackerCustomizer serviceTrackerCustomizer);
90
91 /**
92 * Additional interface for implementations which support reference installation.
93 */
94 interface AllowsReferenceInstall
95 {
96 /**
97 * Installs a bundle into a running OSGI container.
98 *
99 * @param file The bundle file to install.
100 * @param allowReference true iff the file need not be copied, and the container may install
101 * a reference to it.
102 * @return The installed bundle.
103 * @throws OsgiContainerException If the bundle cannot be loaded
104 */
105 Bundle installBundle(File file, boolean allowReference) throws OsgiContainerException;
106
107 /**
108 * Host class for a static installBundle(OsgiContainerManager, File, boolean) which defaults
109 * to OsgiContainerManager.install(File, false).
110 */
111 class Default
112 {
113 /**
114 * Install a bundle as a reference if supported and requested.
115 *
116 * If the OsgiContainerManager supports AllowsReferenceInstall, we allow it to decide
117 * whether to reference install, otherwise we fallback to the {@link
118 * OsgiContainerManager#installBundle(File)} api for a nonreference install.
119 *
120 * @param osgiContainerManager the OsgiContainerManager to install into.
121 * @param file The bundle file to install.
122 * @param allowReference true iff the file need not be copied, and the container
123 * may install a reference to it.
124 * @return the installed bundle.
125 */
126 public static Bundle installBundle(OsgiContainerManager osgiContainerManager, File file, boolean allowReference)
127 throws OsgiContainerException
128 {
129 if (osgiContainerManager instanceof AllowsReferenceInstall)
130 {
131 return ((AllowsReferenceInstall) osgiContainerManager).installBundle(file, allowReference);
132 }
133 else
134 {
135 return osgiContainerManager.installBundle(file);
136 }
137 }
138 }
139
140 }
141 }