You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@karaf.apache.org by gn...@apache.org on 2012/01/05 15:16:38 UTC
svn commit: r1227602 [7/10] - in /karaf/trunk: ./ admin/command/ admin/core/
admin/core/src/test/java/org/apache/karaf/jpm/ admin/management/
deployer/blueprint/ deployer/features/ deployer/kar/ deployer/spring/
deployer/wrap/ diagnostic/command/ diagn...
Added: karaf/trunk/main/src/main/java/org/osgi/framework/SynchronousBundleListener.java
URL: http://svn.apache.org/viewvc/karaf/trunk/main/src/main/java/org/osgi/framework/SynchronousBundleListener.java?rev=1227602&view=auto
==============================================================================
--- karaf/trunk/main/src/main/java/org/osgi/framework/SynchronousBundleListener.java (added)
+++ karaf/trunk/main/src/main/java/org/osgi/framework/SynchronousBundleListener.java Thu Jan 5 14:16:33 2012
@@ -0,0 +1,66 @@
+/*
+ * Copyright (c) OSGi Alliance (2001, 2010). All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.osgi.framework;
+
+/**
+ * A synchronous {@code BundleEvent} listener.
+ * {@code SynchronousBundleListener} is a listener interface that may be
+ * implemented by a bundle developer. When a {@code BundleEvent} is fired,
+ * it is synchronously delivered to a {@code SynchronousBundleListener}.
+ * The Framework may deliver {@code BundleEvent} objects to a
+ * {@code SynchronousBundleListener} out of order and may concurrently call
+ * and/or reenter a {@code SynchronousBundleListener}.
+ *
+ * <p>
+ * For {@code BundleEvent} types {@link BundleEvent#STARTED STARTED} and
+ * {@link BundleEvent#LAZY_ACTIVATION LAZY_ACTIVATION}, the Framework must not
+ * hold the referenced bundle's "state change" lock when the
+ * {@code BundleEvent} is delivered to a
+ * {@code SynchronousBundleListener}. For the other
+ * {@code BundleEvent} types, the Framework must hold the referenced
+ * bundle's "state change" lock when the {@code BundleEvent} is
+ * delivered to a {@code SynchronousBundleListener}. A
+ * {@code SynchronousBundleListener} cannot directly call life cycle
+ * methods on the referenced bundle when the Framework is holding the referenced
+ * bundle's "state change" lock.
+ *
+ * <p>
+ * A {@code SynchronousBundleListener} object is registered with the
+ * Framework using the {@link BundleContext#addBundleListener} method.
+ * {@code SynchronousBundleListener} objects are called with a
+ * {@code BundleEvent} object when a bundle has been installed, resolved,
+ * starting, started, stopping, stopped, updated, unresolved, or uninstalled.
+ * <p>
+ * Unlike normal {@code BundleListener} objects,
+ * {@code SynchronousBundleListener}s are synchronously called during
+ * bundle lifecycle processing. The bundle lifecycle processing will not proceed
+ * until all {@code SynchronousBundleListener}s have completed.
+ * {@code SynchronousBundleListener} objects will be called prior to
+ * {@code BundleListener} objects.
+ * <p>
+ * {@code AdminPermission[bundle,LISTENER]} is required to add or remove a
+ * {@code SynchronousBundleListener} object.
+ *
+ * @since 1.1
+ * @see BundleEvent
+ * @ThreadSafe
+ * @version $Id: b22484f48ebdcb2141da9bba9eb65f5c40e0f520 $
+ */
+
+public interface SynchronousBundleListener extends BundleListener {
+ // This is a marker interface
+}
Added: karaf/trunk/main/src/main/java/org/osgi/framework/Version.java
URL: http://svn.apache.org/viewvc/karaf/trunk/main/src/main/java/org/osgi/framework/Version.java?rev=1227602&view=auto
==============================================================================
--- karaf/trunk/main/src/main/java/org/osgi/framework/Version.java (added)
+++ karaf/trunk/main/src/main/java/org/osgi/framework/Version.java Thu Jan 5 14:16:33 2012
@@ -0,0 +1,376 @@
+/*
+ * Copyright (c) OSGi Alliance (2004, 2010). All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.osgi.framework;
+
+import java.util.NoSuchElementException;
+import java.util.StringTokenizer;
+
+/**
+ * Version identifier for bundles and packages.
+ *
+ * <p>
+ * Version identifiers have four components.
+ * <ol>
+ * <li>Major version. A non-negative integer.</li>
+ * <li>Minor version. A non-negative integer.</li>
+ * <li>Micro version. A non-negative integer.</li>
+ * <li>Qualifier. A text string. See {@code Version(String)} for the
+ * format of the qualifier string.</li>
+ * </ol>
+ *
+ * <p>
+ * {@code Version} objects are immutable.
+ *
+ * @since 1.3
+ * @Immutable
+ * @version $Id: a71e2e2d7685e65b5bbe375efdf97fda16eff0a5 $
+ */
+
+public class Version implements Comparable<Version> {
+ private final int major;
+ private final int minor;
+ private final int micro;
+ private final String qualifier;
+ private static final String SEPARATOR = ".";
+ private transient String versionString;
+
+ /**
+ * The empty version "0.0.0".
+ */
+ public static final Version emptyVersion = new Version(0, 0, 0);
+
+ /**
+ * Creates a version identifier from the specified numerical components.
+ *
+ * <p>
+ * The qualifier is set to the empty string.
+ *
+ * @param major Major component of the version identifier.
+ * @param minor Minor component of the version identifier.
+ * @param micro Micro component of the version identifier.
+ * @throws IllegalArgumentException If the numerical components are
+ * negative.
+ */
+ public Version(int major, int minor, int micro) {
+ this(major, minor, micro, null);
+ }
+
+ /**
+ * Creates a version identifier from the specified components.
+ *
+ * @param major Major component of the version identifier.
+ * @param minor Minor component of the version identifier.
+ * @param micro Micro component of the version identifier.
+ * @param qualifier Qualifier component of the version identifier. If
+ * {@code null} is specified, then the qualifier will be set to
+ * the empty string.
+ * @throws IllegalArgumentException If the numerical components are negative
+ * or the qualifier string is invalid.
+ */
+ public Version(int major, int minor, int micro, String qualifier) {
+ if (qualifier == null) {
+ qualifier = "";
+ }
+
+ this.major = major;
+ this.minor = minor;
+ this.micro = micro;
+ this.qualifier = qualifier;
+ versionString = null;
+ validate();
+ }
+
+ /**
+ * Created a version identifier from the specified string.
+ *
+ * <p>
+ * Here is the grammar for version strings.
+ *
+ * <pre>
+ * version ::= major('.'minor('.'micro('.'qualifier)?)?)?
+ * major ::= digit+
+ * minor ::= digit+
+ * micro ::= digit+
+ * qualifier ::= (alpha|digit|'_'|'-')+
+ * digit ::= [0..9]
+ * alpha ::= [a..zA..Z]
+ * </pre>
+ *
+ * There must be no whitespace in version.
+ *
+ * @param version String representation of the version identifier.
+ * @throws IllegalArgumentException If {@code version} is improperly
+ * formatted.
+ */
+ public Version(String version) {
+ int maj = 0;
+ int min = 0;
+ int mic = 0;
+ String qual = "";
+
+ try {
+ StringTokenizer st = new StringTokenizer(version, SEPARATOR, true);
+ maj = Integer.parseInt(st.nextToken());
+
+ if (st.hasMoreTokens()) { // minor
+ st.nextToken(); // consume delimiter
+ min = Integer.parseInt(st.nextToken());
+
+ if (st.hasMoreTokens()) { // micro
+ st.nextToken(); // consume delimiter
+ mic = Integer.parseInt(st.nextToken());
+
+ if (st.hasMoreTokens()) { // qualifier
+ st.nextToken(); // consume delimiter
+ qual = st.nextToken(""); // remaining string
+
+ if (st.hasMoreTokens()) { // fail safe
+ throw new IllegalArgumentException(
+ "invalid format: " + version);
+ }
+ }
+ }
+ }
+ }
+ catch (NoSuchElementException e) {
+ IllegalArgumentException iae = new IllegalArgumentException(
+ "invalid format: " + version);
+ iae.initCause(e);
+ throw iae;
+ }
+
+ major = maj;
+ minor = min;
+ micro = mic;
+ qualifier = qual;
+ versionString = null;
+ validate();
+ }
+
+ /**
+ * Called by the Version constructors to validate the version components.
+ *
+ * @throws IllegalArgumentException If the numerical components are negative
+ * or the qualifier string is invalid.
+ */
+ private void validate() {
+ if (major < 0) {
+ throw new IllegalArgumentException("negative major");
+ }
+ if (minor < 0) {
+ throw new IllegalArgumentException("negative minor");
+ }
+ if (micro < 0) {
+ throw new IllegalArgumentException("negative micro");
+ }
+ char[] chars = qualifier.toCharArray();
+ for (int i = 0, length = chars.length; i < length; i++) {
+ char ch = chars[i];
+ if (('A' <= ch) && (ch <= 'Z')) {
+ continue;
+ }
+ if (('a' <= ch) && (ch <= 'z')) {
+ continue;
+ }
+ if (('0' <= ch) && (ch <= '9')) {
+ continue;
+ }
+ if ((ch == '_') || (ch == '-')) {
+ continue;
+ }
+ throw new IllegalArgumentException("invalid qualifier: "
+ + qualifier);
+ }
+ }
+
+ /**
+ * Parses a version identifier from the specified string.
+ *
+ * <p>
+ * See {@code Version(String)} for the format of the version string.
+ *
+ * @param version String representation of the version identifier. Leading
+ * and trailing whitespace will be ignored.
+ * @return A {@code Version} object representing the version
+ * identifier. If {@code version} is {@code null} or
+ * the empty string then {@code emptyVersion} will be
+ * returned.
+ * @throws IllegalArgumentException If {@code version} is improperly
+ * formatted.
+ */
+ public static Version parseVersion(String version) {
+ if (version == null) {
+ return emptyVersion;
+ }
+
+ version = version.trim();
+ if (version.length() == 0) {
+ return emptyVersion;
+ }
+
+ return new Version(version);
+ }
+
+ /**
+ * Returns the major component of this version identifier.
+ *
+ * @return The major component.
+ */
+ public int getMajor() {
+ return major;
+ }
+
+ /**
+ * Returns the minor component of this version identifier.
+ *
+ * @return The minor component.
+ */
+ public int getMinor() {
+ return minor;
+ }
+
+ /**
+ * Returns the micro component of this version identifier.
+ *
+ * @return The micro component.
+ */
+ public int getMicro() {
+ return micro;
+ }
+
+ /**
+ * Returns the qualifier component of this version identifier.
+ *
+ * @return The qualifier component.
+ */
+ public String getQualifier() {
+ return qualifier;
+ }
+
+ /**
+ * Returns the string representation of this version identifier.
+ *
+ * <p>
+ * The format of the version string will be {@code major.minor.micro}
+ * if qualifier is the empty string or
+ * {@code major.minor.micro.qualifier} otherwise.
+ *
+ * @return The string representation of this version identifier.
+ */
+ public String toString() {
+ if (versionString != null) {
+ return versionString;
+ }
+ int q = qualifier.length();
+ StringBuffer result = new StringBuffer(20 + q);
+ result.append(major);
+ result.append(SEPARATOR);
+ result.append(minor);
+ result.append(SEPARATOR);
+ result.append(micro);
+ if (q > 0) {
+ result.append(SEPARATOR);
+ result.append(qualifier);
+ }
+ return versionString = result.toString();
+ }
+
+ /**
+ * Returns a hash code value for the object.
+ *
+ * @return An integer which is a hash code value for this object.
+ */
+ public int hashCode() {
+ return (major << 24) + (minor << 16) + (micro << 8)
+ + qualifier.hashCode();
+ }
+
+ /**
+ * Compares this {@code Version} object to another object.
+ *
+ * <p>
+ * A version is considered to be <b>equal to </b> another version if the
+ * major, minor and micro components are equal and the qualifier component
+ * is equal (using {@code String.equals}).
+ *
+ * @param object The {@code Version} object to be compared.
+ * @return {@code true} if {@code object} is a
+ * {@code Version} and is equal to this object;
+ * {@code false} otherwise.
+ */
+ public boolean equals(Object object) {
+ if (object == this) { // quicktest
+ return true;
+ }
+
+ if (!(object instanceof Version)) {
+ return false;
+ }
+
+ Version other = (Version) object;
+ return (major == other.major) && (minor == other.minor)
+ && (micro == other.micro) && qualifier.equals(other.qualifier);
+ }
+
+ /**
+ * Compares this {@code Version} object to another {@code Version}.
+ *
+ * <p>
+ * A version is considered to be <b>less than </b> another version if its
+ * major component is less than the other version's major component, or the
+ * major components are equal and its minor component is less than the other
+ * version's minor component, or the major and minor components are equal
+ * and its micro component is less than the other version's micro component,
+ * or the major, minor and micro components are equal and it's qualifier
+ * component is less than the other version's qualifier component (using
+ * {@code String.compareTo}).
+ *
+ * <p>
+ * A version is considered to be <b>equal to</b> another version if the
+ * major, minor and micro components are equal and the qualifier component
+ * is equal (using {@code String.compareTo}).
+ *
+ * @param other The {@code Version} object to be compared.
+ * @return A negative integer, zero, or a positive integer if this version
+ * is less than, equal to, or greater than the specified
+ * {@code Version} object.
+ * @throws ClassCastException If the specified object is not a
+ * {@code Version} object.
+ */
+ public int compareTo(Version other) {
+ if (other == this) { // quicktest
+ return 0;
+ }
+
+ int result = major - other.major;
+ if (result != 0) {
+ return result;
+ }
+
+ result = minor - other.minor;
+ if (result != 0) {
+ return result;
+ }
+
+ result = micro - other.micro;
+ if (result != 0) {
+ return result;
+ }
+
+ return qualifier.compareTo(other.qualifier);
+ }
+}
Added: karaf/trunk/main/src/main/java/org/osgi/framework/hooks/bundle/EventHook.java
URL: http://svn.apache.org/viewvc/karaf/trunk/main/src/main/java/org/osgi/framework/hooks/bundle/EventHook.java?rev=1227602&view=auto
==============================================================================
--- karaf/trunk/main/src/main/java/org/osgi/framework/hooks/bundle/EventHook.java (added)
+++ karaf/trunk/main/src/main/java/org/osgi/framework/hooks/bundle/EventHook.java Thu Jan 5 14:16:33 2012
@@ -0,0 +1,60 @@
+/*
+ * Copyright (c) OSGi Alliance (2010). All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.osgi.framework.hooks.bundle;
+
+import java.util.Collection;
+
+import org.osgi.framework.BundleContext;
+import org.osgi.framework.BundleEvent;
+
+/**
+ * OSGi Framework Bundle Event Hook Service.
+ *
+ * <p>
+ * Bundles registering this service will be called during framework lifecycle
+ * (install, start, stop, update, and uninstall bundle) operations.
+ *
+ * @ThreadSafe
+ * @version $Id: 18ea1ec1f14f47410a43e99be4da3b2583149722 $
+ */
+public interface EventHook {
+
+ /**
+ * Bundle event hook method. This method is called prior to bundle event
+ * delivery when a bundle is installed, resolved, started, stopped, unresolved, or
+ * uninstalled. This method can filter the bundles which receive the event.
+ * <p>
+ * This method must be called by the framework one and only one time for each bundle
+ * event generated, this included bundle events which are generated when there are no
+ * bundle listeners registered. This method must be called on the same thread that is
+ * performing the action which generated the specified event. The specified
+ * collection includes bundle contexts with synchronous and asynchronous bundle
+ * listeners registered with them.
+ *
+ * @param event The bundle event to be delivered
+ * @param contexts A collection of Bundle Contexts for bundles which have
+ * listeners to which the specified event will be delivered. The
+ * implementation of this method may remove bundle contexts from the
+ * collection to prevent the event from being delivered to the
+ * associated bundles. The collection supports all the optional
+ * {@code Collection} operations except {@code add} and
+ * {@code addAll}. Attempting to add to the collection will
+ * result in an {@code UnsupportedOperationException}. The
+ * collection is not synchronized.
+ */
+ void event(BundleEvent event, Collection<BundleContext> contexts);
+}
Added: karaf/trunk/main/src/main/java/org/osgi/framework/hooks/bundle/FindHook.java
URL: http://svn.apache.org/viewvc/karaf/trunk/main/src/main/java/org/osgi/framework/hooks/bundle/FindHook.java?rev=1227602&view=auto
==============================================================================
--- karaf/trunk/main/src/main/java/org/osgi/framework/hooks/bundle/FindHook.java (added)
+++ karaf/trunk/main/src/main/java/org/osgi/framework/hooks/bundle/FindHook.java Thu Jan 5 14:16:33 2012
@@ -0,0 +1,66 @@
+/*
+ * Copyright (c) OSGi Alliance (2011). All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package org.osgi.framework.hooks.bundle;
+
+import java.util.Collection;
+
+import org.osgi.framework.Bundle;
+import org.osgi.framework.BundleContext;
+import org.osgi.framework.BundleException;
+
+/**
+ * OSGi Framework Bundle Context Hook Service.
+ *
+ * <p>
+ * Bundles registering this service will be called during framework bundle find
+ * (get bundles) operations.
+ *
+ * @ThreadSafe
+ * @version $Id: 4492a677df650072fe6acaea9ea35571f31eb5a9 $
+ */
+public interface FindHook {
+ /**
+ * Find hook method. This method is called for the following:
+ * <ul>
+ * <li>Bundle find operations using {@link BundleContext#getBundle(long)}
+ * and {@link BundleContext#getBundles()} methods. The find method can
+ * filter the result of the find operation. Note that a find operation using
+ * the {@link BundleContext#getBundle(String)} method does not cause the
+ * find method to be called.</li>
+ * <li>Bundle install operations when an existing bundle is already
+ * installed at a given location. In this case, the find method is called to
+ * determine if the context performing the install operation is able to find
+ * the bundle. If the context cannot find the existing bundle then the
+ * install operation must fail with a
+ * {@link BundleException#REJECTED_BY_HOOK} exception.</li>
+ * </ul>
+ *
+ * @param context
+ * The bundle context of the bundle performing the find
+ * operation.
+ * @param bundles
+ * A collection of Bundles to be returned as a result of the find
+ * operation. The implementation of this method may remove
+ * bundles from the collection to prevent the bundles from being
+ * returned to the bundle performing the find operation. The
+ * collection supports all the optional {@code Collection}
+ * operations except {@code add} and {@code addAll}. Attempting
+ * to add to the collection will result in an
+ * {@code UnsupportedOperationException}. The collection is not
+ * synchronized.
+ */
+ void find(BundleContext context, Collection<Bundle> bundles);
+}
Added: karaf/trunk/main/src/main/java/org/osgi/framework/hooks/bundle/package-info.java
URL: http://svn.apache.org/viewvc/karaf/trunk/main/src/main/java/org/osgi/framework/hooks/bundle/package-info.java?rev=1227602&view=auto
==============================================================================
--- karaf/trunk/main/src/main/java/org/osgi/framework/hooks/bundle/package-info.java (added)
+++ karaf/trunk/main/src/main/java/org/osgi/framework/hooks/bundle/package-info.java Thu Jan 5 14:16:33 2012
@@ -0,0 +1,32 @@
+/*
+ * Copyright (c) OSGi Alliance (2010). All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Framework Bundle Hooks Package Version 1.0.
+ *
+ * <p>
+ * Bundles wishing to use this package must list the package in the
+ * Import-Package header of the bundle's manifest.
+ *
+ * <p>
+ * Example import for consumers using the API in this package:
+ * <p>
+ * {@code Import-Package: org.osgi.framework.hooks.bundle; version="[1.0,2.0)"}
+ *
+ * @version $Id: a609772e6106eb5b93ec337740e48696417fc082 $
+ */
+
+package org.osgi.framework.hooks.bundle;
Added: karaf/trunk/main/src/main/java/org/osgi/framework/hooks/bundle/packageinfo
URL: http://svn.apache.org/viewvc/karaf/trunk/main/src/main/java/org/osgi/framework/hooks/bundle/packageinfo?rev=1227602&view=auto
==============================================================================
--- karaf/trunk/main/src/main/java/org/osgi/framework/hooks/bundle/packageinfo (added)
+++ karaf/trunk/main/src/main/java/org/osgi/framework/hooks/bundle/packageinfo Thu Jan 5 14:16:33 2012
@@ -0,0 +1 @@
+version 1.0
Added: karaf/trunk/main/src/main/java/org/osgi/framework/hooks/resolver/ResolverHook.java
URL: http://svn.apache.org/viewvc/karaf/trunk/main/src/main/java/org/osgi/framework/hooks/resolver/ResolverHook.java?rev=1227602&view=auto
==============================================================================
--- karaf/trunk/main/src/main/java/org/osgi/framework/hooks/resolver/ResolverHook.java (added)
+++ karaf/trunk/main/src/main/java/org/osgi/framework/hooks/resolver/ResolverHook.java Thu Jan 5 14:16:33 2012
@@ -0,0 +1,198 @@
+/*
+ * Copyright (c) OSGi Alliance (2010, 2011). All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.osgi.framework.hooks.resolver;
+
+import java.util.Collection;
+
+import org.osgi.framework.Bundle;
+import org.osgi.framework.wiring.BundleCapability;
+import org.osgi.framework.wiring.BundleRequirement;
+import org.osgi.framework.wiring.BundleRevision;
+import org.osgi.framework.wiring.FrameworkWiring;
+
+/**
+ * OSGi Framework Resolver Hook instances are obtained from the OSGi
+ * {@link ResolverHookFactory Framework Resolver Hook Factory} service.
+ *
+ * <p>
+ * A Resolver Hook instance is called by the framework during a resolve process.
+ * A resolver hook may influence the outcome of a resolve process by removing
+ * entries from shrinkable collections that are passed to the hook during a
+ * resolve process. A shrinkable collection is a {@code Collection} that
+ * supports all remove operations. Any other attempts to modify a shrinkable
+ * collection will result in an {@code UnsupportedOperationException} being
+ * thrown.
+ *
+ * <p>
+ * The following steps outline the way a framework uses the resolver hooks
+ * during a resolve process.
+ * <ol>
+ * <li>Collect a snapshot of registered resolver hook factories that will be
+ * called during the current resolve process. Any hook factories registered
+ * after the snapshot is taken must not be called during the current resolve
+ * process. A resolver hook factory contained in the snapshot may become
+ * unregistered during the resolve process. The framework should handle this and
+ * stop calling the resolver hook instance provided by the unregistered hook
+ * factory and the current resolve process must fail. If possible, an exception
+ * must be thrown to the caller of the API which triggered the resolve process.
+ * In cases where the the caller is not available a framework event of type
+ * error should be fired.</li>
+ * <li>For each registered hook factory call the
+ * {@link ResolverHookFactory#begin(Collection)} method to inform the hooks
+ * about a resolve process beginning and to obtain a Resolver Hook instance that
+ * will be used for the duration of the resolve process.</li>
+ * <li>Determine the collection of unresolved bundle revisions that may be
+ * considered for resolution during the current resolution process and place
+ * each of the bundle revisions in a shrinkable collection {@code R}. For each
+ * resolver hook call the {@link #filterResolvable(Collection)} method with the
+ * shrinkable collection {@code R}.</li>
+ * <li>The shrinkable collection {@code R} now contains all the unresolved
+ * bundle revisions that may end up as resolved at the end of the current
+ * resolve process. Any other bundle revisions that got removed from the
+ * shrinkable collection {@code R} must not end up as resolved at the end of the
+ * current resolve process.</li>
+ * <li>For each bundle revision {@code B} left in the shrinkable collection
+ * {@code R} that represents a singleton bundle do the following:<br/>
+ * Determine the collection of available capabilities that have a name space of
+ * {@link BundleRevision#BUNDLE_NAMESPACE osgi.wiring.bundle}, are singletons,
+ * and have the same symbolic name as the singleton bundle revision {@code B}
+ * and place each of the matching capabilities into a shrinkable collection
+ * {@code S}.
+ *
+ * Remove the {@link BundleRevision#BUNDLE_NAMESPACE osgi.wiring.bundle}
+ * capability provided by bundle revision {@code B} from shrinkable collection
+ * {@code S}. A singleton bundle cannot collide with itself.
+ *
+ * For each resolver hook call the
+ * {@link #filterSingletonCollisions(BundleCapability, Collection)} with the
+ * {@link BundleRevision#BUNDLE_NAMESPACE osgi.wiring.bundle} capability
+ * provided by bundle revision {@code B} and the shrinkable collection {@code S}
+ *
+ * The shrinkable collection {@code S} now contains all singleton
+ * {@link BundleRevision#BUNDLE_NAMESPACE osgi.wiring.bundle} capabilities that
+ * can influence the ability of bundle revision {@code B} to resolve.</li>
+ * <li>During a resolve process a framework is free to attempt to resolve any or
+ * all bundles contained in shrinkable collection {@code R}. For each bundle
+ * revision {@code B} left in the shrinkable collection {@code R} which the
+ * framework attempts to resolve the following steps must be followed:
+ * <p/>
+ * For each requirement {@code T} specified by bundle revision {@code B}
+ * determine the collection of capabilities that satisfy (or match) the
+ * requirement and place each matching capability into a shrinkable collection
+ * {@code C}. A capability is considered to match a particular requirement if
+ * its attributes satisfy a specified requirement and the requirer bundle has
+ * permission to access the capability.
+ *
+ * <p/>
+ * For each resolver hook call the
+ * {@link #filterMatches(BundleRequirement, Collection)} with the requirement
+ * {@code T} and the shrinkable collection {@code C}.
+ *
+ * <p/>
+ * The shrinkable collection {@code C} now contains all the capabilities that
+ * may be used to satisfy the requirement {@code T}. Any other capabilities that
+ * got removed from the shrinkable collection {@code C} must not be used to
+ * satisfy requirement {@code T}.</li>
+ * <li>For each resolver hook call the {@link #end()} method to inform the hooks
+ * about a resolve process ending.</li>
+ * </ol>
+ * In all cases, the order in which the resolver hooks are called is the reverse
+ * compareTo ordering of their Service References. That is, the service with the
+ * highest ranking number must be called first. In cases where a shrinkable
+ * collection becomes empty the framework is required to call the remaining
+ * registered hooks.
+ * <p>
+ * Resolver hooks are low level. Implementations of the resolver hook must be
+ * careful not to create an unresolvable state which is very hard for a
+ * developer or a provisioner to diagnose. Resolver hooks also must not be
+ * allowed to start another synchronous resolve process (e.g. by calling
+ * {@link Bundle#start()} or {@link FrameworkWiring#resolveBundles(Collection)}
+ * ). The framework must detect this and throw an {@link IllegalStateException}.
+ *
+ * @see ResolverHookFactory
+ * @NotThreadSafe
+ * @version $Id: ea23400257d780706250f8825ec886aaebb0e5d8 $
+ */
+public interface ResolverHook {
+ /**
+ * Filter resolvable candidates hook method. This method may be called
+ * multiple times during a single resolve process.
+ * This method can filter the collection of candidates by removing
+ * potential candidates. Removing a candidate will prevent the candidate
+ * from resolving during the current resolve process.
+ *
+ * @param candidates the collection of resolvable candidates available during
+ * a resolve process.
+ */
+ void filterResolvable(Collection<BundleRevision> candidates);
+
+ /**
+ * Filter singleton collisions hook method. This method is called during the
+ * resolve process for the specified singleton. The specified singleton
+ * represents a singleton capability and the specified collection represent
+ * a collection of singleton capabilities which are considered collision
+ * candidates. The singleton capability and the collection of collision
+ * candidates must all use the same name space.
+ * <p>
+ * Currently only capabilities with the name space of
+ * {@link BundleRevision#BUNDLE_NAMESPACE osgi.wiring.bundle} can be
+ * singletons. In that case all the collision candidates have the name space
+ * of {@link BundleRevision#BUNDLE_NAMESPACE osgi.wiring.bundle}, are
+ * singletons, and have the same symbolic name as the specified singleton
+ * capability.
+ * <p>
+ * In the future, capabilities in other name spaces may support the
+ * singleton concept. Hook implementations should be prepared to receive
+ * calls to this method for capabilities in name spaces other than
+ * {@link BundleRevision#BUNDLE_NAMESPACE osgi.wiring.bundle}.
+ * <p>
+ * This method can filter the list of collision candidates by removing
+ * potential collisions. Removing a collision candidate will allow the
+ * specified singleton to resolve regardless of the resolution state of the
+ * removed collision candidate.
+ *
+ * @param singleton the singleton involved in a resolve process
+ * @param collisionCandidates a collection of singleton collision candidates
+ */
+ void filterSingletonCollisions(BundleCapability singleton, Collection<BundleCapability> collisionCandidates);
+
+ /**
+ * Filter matches hook method. This method is called during the resolve process for the
+ * specified requirement. The collection of candidates match the specified requirement.
+ * This method can filter the collection of matching candidates by removing candidates from
+ * the collection. Removing a candidate will prevent the resolve process from choosing the
+ * removed candidate to satisfy the requirement.
+ * <p>
+ * All of the candidates will have the same name space and will
+ * match the specified requirement.
+ * <p>
+ * If the Java Runtime Environment supports permissions then the collection of
+ * candidates will only contain candidates for which the requirer has permission to
+ * access.
+ * @param requirement the requirement to filter candidates for
+ * @param candidates a collection of candidates that match the requirement
+ */
+ void filterMatches(BundleRequirement requirement, Collection<BundleCapability> candidates);
+
+ /**
+ * This method is called once at the end of the resolve process.
+ * After the end method is called the resolve process has ended.
+ * The framework must not hold onto this resolver hook instance
+ * after end has been called.
+ */
+ void end();
+}
Added: karaf/trunk/main/src/main/java/org/osgi/framework/hooks/resolver/ResolverHookFactory.java
URL: http://svn.apache.org/viewvc/karaf/trunk/main/src/main/java/org/osgi/framework/hooks/resolver/ResolverHookFactory.java?rev=1227602&view=auto
==============================================================================
--- karaf/trunk/main/src/main/java/org/osgi/framework/hooks/resolver/ResolverHookFactory.java (added)
+++ karaf/trunk/main/src/main/java/org/osgi/framework/hooks/resolver/ResolverHookFactory.java Thu Jan 5 14:16:33 2012
@@ -0,0 +1,94 @@
+/*
+ * Copyright (c) OSGi Alliance (2011). All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.osgi.framework.hooks.resolver;
+
+import java.util.Collection;
+
+import org.osgi.framework.Bundle;
+import org.osgi.framework.wiring.BundleRevision;
+import org.osgi.framework.wiring.FrameworkWiring;
+
+/**
+ * OSGi Framework Resolver Hook Factory Service.
+ *
+ * <p>
+ * Bundles registering this service will be called by the framework during
+ * a bundle resolver process to obtain a {@link ResolverHook resolver hook}
+ * instance which will be used for the duration of a resolve process.
+ *
+ * @ThreadSafe
+ * @see ResolverHook
+ * @version $Id: 4023566367435f07c047a7ba571f3bedc53aa37a $
+ */
+public interface ResolverHookFactory {
+ /**
+ * This method is called by the framework each time a resolve process begins
+ * to obtain a {@link ResolverHook resolver hook} instance. This resolver hook
+ * instance will be used for the duration of the resolve process. At the end of
+ * the resolve process the method {@link ResolverHook#end()} must be called by
+ * the framework and the framework must not hold any references of the resolver
+ * hook instance.
+ * <p>
+ * The triggers represent the collection of bundles which triggered
+ * the resolve process. This collection may be empty if the triggers
+ * cannot be determined by the framework. In most cases the triggers
+ * can easily be determined. Calling certain methods on
+ * {@link Bundle bundle} when a bundle is in the {@link Bundle#INSTALLED INSTALLED}
+ * state will cause the framework to begin a resolve process in order to resolve the
+ * bundle. The following methods will start a resolve process in this case:
+ * <ul>
+ * <li>{@link Bundle#start() start}</li>
+ * <li>{@link Bundle#loadClass(String) loadClass}</li>
+ * <li>{@link Bundle#findEntries(String, String, boolean) findEntries}</li>
+ * <li>{@link Bundle#getResource(String) getResource}</li>
+ * <li>{@link Bundle#getResources(String) getResources}</li>
+ * </ul>
+ * In such cases the collection will contain the single bundle which the
+ * framework is trying to resolve. Other cases will cause multiple bundles to be
+ * included in the trigger bundles collection. When {@link FrameworkWiring#resolveBundles(Collection)
+ * resolveBundles} is called the collection of triggers must include all the current bundle
+ * revisions for bundles passed to resolveBundles which are in the {@link Bundle#INSTALLED INSTALLED}
+ * state.
+ * <p>
+ * When {@link FrameworkWiring#refreshBundles(Collection, org.osgi.framework.FrameworkListener...)}
+ * is called the collection of triggers is determined with the following steps:
+ * <ul>
+ * <li>If the collection of bundles passed is null then {@link FrameworkWiring#getRemovalPendingBundles()}
+ * is called to get the initial collection of bundles.</li>
+ * <li>The equivalent of calling {@link FrameworkWiring#getDependencyClosure(Collection)} is called with
+ * the initial collection of bundles to get the dependency closure collection of the bundles being refreshed.</li>
+ * <li>Remove any non-active bundles from the dependency closure collection.</li>
+ * <li>For each bundle remaining in the dependency closure collection get the current bundle revision
+ * and add it to the collection of triggers.</li>
+ * </ul>
+ * <p>
+ * As described above, a resolve process is typically initiated as a result of calling API that causes the
+ * framework to attempt to resolve one or more bundles.
+ * The framework is free to start a resolve process at any time for reasons other than calls to framework API.
+ * For example, a resolve process may be used by the framework for diagnostic purposes and result in no
+ * bundles actually becoming resolved at the end of the process.
+ * Resolver hook implementations must be prepared for resolve processes that are initiated for other reasons
+ * besides calls to framework API.
+ * @param triggers an unmodifiable collection of bundles which triggered the resolve process.
+ * This collection may be empty if the collection of trigger bundles cannot be
+ * determined.
+ * @return a resolver hook instance to be used for the duration of the resolve process.
+ * A {@code null} value may be returned which indicates this resolver hook factory abstains from
+ * the resolve process.
+ */
+ ResolverHook begin(Collection<BundleRevision> triggers);
+}
Added: karaf/trunk/main/src/main/java/org/osgi/framework/hooks/resolver/package-info.java
URL: http://svn.apache.org/viewvc/karaf/trunk/main/src/main/java/org/osgi/framework/hooks/resolver/package-info.java?rev=1227602&view=auto
==============================================================================
--- karaf/trunk/main/src/main/java/org/osgi/framework/hooks/resolver/package-info.java (added)
+++ karaf/trunk/main/src/main/java/org/osgi/framework/hooks/resolver/package-info.java Thu Jan 5 14:16:33 2012
@@ -0,0 +1,32 @@
+/*
+ * Copyright (c) OSGi Alliance (2010). All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Framework Resolver Hooks Package Version 1.0.
+ *
+ * <p>
+ * Bundles wishing to use this package must list the package in the
+ * Import-Package header of the bundle's manifest.
+ *
+ * <p>
+ * Example import for consumers using the API in this package:
+ * <p>
+ * {@code Import-Package: org.osgi.framework.hooks.resolver; version="[1.0,2.0)"}
+ *
+ * @version $Id: 93dc1d16f50055fd55daff71eb5df5eed3371957 $
+ */
+
+package org.osgi.framework.hooks.resolver;
Added: karaf/trunk/main/src/main/java/org/osgi/framework/hooks/resolver/packageinfo
URL: http://svn.apache.org/viewvc/karaf/trunk/main/src/main/java/org/osgi/framework/hooks/resolver/packageinfo?rev=1227602&view=auto
==============================================================================
--- karaf/trunk/main/src/main/java/org/osgi/framework/hooks/resolver/packageinfo (added)
+++ karaf/trunk/main/src/main/java/org/osgi/framework/hooks/resolver/packageinfo Thu Jan 5 14:16:33 2012
@@ -0,0 +1 @@
+version 1.0
Added: karaf/trunk/main/src/main/java/org/osgi/framework/hooks/service/EventHook.java
URL: http://svn.apache.org/viewvc/karaf/trunk/main/src/main/java/org/osgi/framework/hooks/service/EventHook.java?rev=1227602&view=auto
==============================================================================
--- karaf/trunk/main/src/main/java/org/osgi/framework/hooks/service/EventHook.java (added)
+++ karaf/trunk/main/src/main/java/org/osgi/framework/hooks/service/EventHook.java Thu Jan 5 14:16:33 2012
@@ -0,0 +1,54 @@
+/*
+ * Copyright (c) OSGi Alliance (2008, 2010). All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.osgi.framework.hooks.service;
+
+import java.util.Collection;
+
+import org.osgi.framework.BundleContext;
+import org.osgi.framework.ServiceEvent;
+
+/**
+ * OSGi Framework Service Event Hook Service.
+ *
+ * <p>
+ * Bundles registering this service will be called during framework service
+ * (register, modify, and unregister service) operations.
+ *
+ * @ThreadSafe
+ * @deprecated As of 1.1. Replaced by {@link EventListenerHook}.
+ * @version $Id: 8fb8cfa2c8847f99fd84711e12f02a57bf06932e $
+ */
+
+public interface EventHook {
+ /**
+ * Event hook method. This method is called prior to service event delivery
+ * when a publishing bundle registers, modifies or unregisters a service.
+ * This method can filter the bundles which receive the event.
+ *
+ * @param event The service event to be delivered.
+ * @param contexts A collection of Bundle Contexts for bundles which have
+ * listeners to which the specified event will be delivered. The
+ * implementation of this method may remove bundle contexts from the
+ * collection to prevent the event from being delivered to the
+ * associated bundles. The collection supports all the optional
+ * {@code Collection} operations except {@code add} and
+ * {@code addAll}. Attempting to add to the collection will
+ * result in an {@code UnsupportedOperationException}. The
+ * collection is not synchronized.
+ */
+ void event(ServiceEvent event, Collection<BundleContext> contexts);
+}
Added: karaf/trunk/main/src/main/java/org/osgi/framework/hooks/service/EventListenerHook.java
URL: http://svn.apache.org/viewvc/karaf/trunk/main/src/main/java/org/osgi/framework/hooks/service/EventListenerHook.java?rev=1227602&view=auto
==============================================================================
--- karaf/trunk/main/src/main/java/org/osgi/framework/hooks/service/EventListenerHook.java (added)
+++ karaf/trunk/main/src/main/java/org/osgi/framework/hooks/service/EventListenerHook.java Thu Jan 5 14:16:33 2012
@@ -0,0 +1,61 @@
+/*
+ * Copyright (c) OSGi Alliance (2010). All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.osgi.framework.hooks.service;
+
+import java.util.Collection;
+import java.util.Map;
+
+import org.osgi.framework.BundleContext;
+import org.osgi.framework.ServiceEvent;
+import org.osgi.framework.hooks.service.ListenerHook.ListenerInfo;
+
+/**
+ * OSGi Framework Service Event Listener Hook Service.
+ *
+ * <p>
+ * Bundles registering this service will be called during framework service
+ * (register, modify, and unregister service) operations.
+ *
+ * @ThreadSafe
+ * @since 1.1
+ * @version $Id: 61c6aa7e7d4c85b3e5a6a3a340155bcda0074505 $
+ */
+
+public interface EventListenerHook {
+ /**
+ * Event listener hook method. This method is called prior to service event
+ * delivery when a publishing bundle registers, modifies or unregisters a
+ * service. This method can filter the listeners which receive the event.
+ *
+ * @param event The service event to be delivered.
+ * @param listeners A map of Bundle Contexts to a collection of Listener
+ * Infos for the bundle's listeners to which the specified event will
+ * be delivered. The implementation of this method may remove bundle
+ * contexts from the map and listener infos from the collection
+ * values to prevent the event from being delivered to the associated
+ * listeners. The map supports all the optional {@code Map}
+ * operations except {@code put} and {@code putAll}. Attempting to
+ * add to the map will result in an
+ * {@code UnsupportedOperationException}. The collection values in
+ * the map supports all the optional {@code Collection} operations
+ * except {@code add} and {@code addAll}. Attempting to add to a
+ * collection will result in an {@code UnsupportedOperationException}
+ * . The map and the collections are not synchronized.
+ */
+ void event(ServiceEvent event,
+ Map<BundleContext, Collection<ListenerInfo>> listeners);
+}
Added: karaf/trunk/main/src/main/java/org/osgi/framework/hooks/service/FindHook.java
URL: http://svn.apache.org/viewvc/karaf/trunk/main/src/main/java/org/osgi/framework/hooks/service/FindHook.java?rev=1227602&view=auto
==============================================================================
--- karaf/trunk/main/src/main/java/org/osgi/framework/hooks/service/FindHook.java (added)
+++ karaf/trunk/main/src/main/java/org/osgi/framework/hooks/service/FindHook.java Thu Jan 5 14:16:33 2012
@@ -0,0 +1,62 @@
+/*
+ * Copyright (c) OSGi Alliance (2008, 2010). All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.osgi.framework.hooks.service;
+
+import java.util.Collection;
+
+import org.osgi.framework.BundleContext;
+import org.osgi.framework.ServiceReference;
+
+/**
+ * OSGi Framework Service Find Hook Service.
+ *
+ * <p>
+ * Bundles registering this service will be called during framework service find
+ * (get service references) operations.
+ *
+ * @ThreadSafe
+ * @version $Id: 4a939200fa6634a563379b057e11bd1b5d174b9d $
+ */
+
+public interface FindHook {
+ /**
+ * Find hook method. This method is called during the service find operation
+ * (for example, {@link BundleContext#getServiceReferences(String, String)}
+ * ). This method can filter the result of the find operation.
+ *
+ * @param context The bundle context of the bundle performing the find
+ * operation.
+ * @param name The class name of the services to find or {@code null}
+ * to find all services.
+ * @param filter The filter criteria of the services to find or
+ * {@code null} for no filter criteria.
+ * @param allServices {@code true} if the find operation is the result
+ * of a call to
+ * {@link BundleContext#getAllServiceReferences(String, String)}
+ * @param references A collection of Service References to be returned as a
+ * result of the find operation. The implementation of this method
+ * may remove service references from the collection to prevent the
+ * references from being returned to the bundle performing the find
+ * operation. The collection supports all the optional
+ * {@code Collection} operations except {@code add} and
+ * {@code addAll}. Attempting to add to the collection will
+ * result in an {@code UnsupportedOperationException}. The
+ * collection is not synchronized.
+ */
+ void find(BundleContext context, String name, String filter,
+ boolean allServices, Collection<ServiceReference< ? >> references);
+}
Added: karaf/trunk/main/src/main/java/org/osgi/framework/hooks/service/ListenerHook.java
URL: http://svn.apache.org/viewvc/karaf/trunk/main/src/main/java/org/osgi/framework/hooks/service/ListenerHook.java?rev=1227602&view=auto
==============================================================================
--- karaf/trunk/main/src/main/java/org/osgi/framework/hooks/service/ListenerHook.java (added)
+++ karaf/trunk/main/src/main/java/org/osgi/framework/hooks/service/ListenerHook.java Thu Jan 5 14:16:33 2012
@@ -0,0 +1,135 @@
+/*
+ * Copyright (c) OSGi Alliance (2008, 2010). All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.osgi.framework.hooks.service;
+
+import java.util.Collection;
+
+import org.osgi.framework.BundleContext;
+
+/**
+ * OSGi Framework Service Listener Hook Service.
+ *
+ * <p>
+ * Bundles registering this service will be called during service listener
+ * addition and removal.
+ *
+ * @ThreadSafe
+ * @version $Id: c1687e95e568589cf3e6d927b7d372c9f88c5d16 $
+ */
+
+public interface ListenerHook {
+ /**
+ * Added listeners hook method. This method is called to provide the hook
+ * implementation with information on newly added service listeners. This
+ * method will be called as service listeners are added while this hook is
+ * registered. Also, immediately after registration of this hook, this
+ * method will be called to provide the current collection of service
+ * listeners which had been added prior to the hook being registered.
+ *
+ * @param listeners A collection of {@link ListenerInfo}s for newly added
+ * service listeners which are now listening to service events.
+ * Attempting to add to or remove from the collection will result in
+ * an {@code UnsupportedOperationException}. The collection is
+ * not synchronized.
+ */
+ void added(Collection<ListenerInfo> listeners);
+
+ /**
+ * Removed listeners hook method. This method is called to provide the hook
+ * implementation with information on newly removed service listeners. This
+ * method will be called as service listeners are removed while this hook is
+ * registered.
+ *
+ * @param listeners A collection of {@link ListenerInfo}s for newly removed
+ * service listeners which are no longer listening to service events.
+ * Attempting to add to or remove from the collection will result in
+ * an {@code UnsupportedOperationException}. The collection is
+ * not synchronized.
+ */
+ void removed(Collection<ListenerInfo> listeners);
+
+ /**
+ * Information about a Service Listener. This interface describes the bundle
+ * which added the Service Listener and the filter with which it was added.
+ *
+ * @ThreadSafe
+ * @noimplement
+ */
+ public interface ListenerInfo {
+ /**
+ * Return the context of the bundle which added the listener.
+ *
+ * @return The context of the bundle which added the listener.
+ */
+ BundleContext getBundleContext();
+
+ /**
+ * Return the filter string with which the listener was added.
+ *
+ * @return The filter string with which the listener was added. This may
+ * be {@code null} if the listener was added without a
+ * filter.
+ */
+ String getFilter();
+
+ /**
+ * Return the state of the listener for this addition and removal life
+ * cycle. Initially this method will return {@code false}
+ * indicating the listener has been added but has not been removed.
+ * After the listener has been removed, this method must always return
+ * {@code true}.
+ *
+ * <p>
+ * There is an extremely rare case in which removed notification to
+ * {@link ListenerHook}s can be made before added notification if two
+ * threads are racing to add and remove the same service listener.
+ * Because {@link ListenerHook}s are called synchronously during service
+ * listener addition and removal, the Framework cannot guarantee
+ * in-order delivery of added and removed notification for a given
+ * service listener. This method can be used to detect this rare
+ * occurrence.
+ *
+ * @return {@code false} if the listener has not been been removed,
+ * {@code true} otherwise.
+ */
+ boolean isRemoved();
+
+ /**
+ * Compares this {@code ListenerInfo} to another
+ * {@code ListenerInfo}. Two {@code ListenerInfo}s are equals
+ * if they refer to the same listener for a given addition and removal
+ * life cycle. If the same listener is added again, it must have a
+ * different {@code ListenerInfo} which is not equal to this
+ * {@code ListenerInfo}.
+ *
+ * @param obj The object to compare against this
+ * {@code ListenerInfo}.
+ * @return {@code true} if the other object is a
+ * {@code ListenerInfo} object and both objects refer to
+ * the same listener for a given addition and removal life
+ * cycle.
+ */
+ boolean equals(Object obj);
+
+ /**
+ * Returns the hash code for this {@code ListenerInfo}.
+ *
+ * @return The hash code of this {@code ListenerInfo}.
+ */
+ int hashCode();
+ }
+}
Added: karaf/trunk/main/src/main/java/org/osgi/framework/hooks/service/package-info.java
URL: http://svn.apache.org/viewvc/karaf/trunk/main/src/main/java/org/osgi/framework/hooks/service/package-info.java?rev=1227602&view=auto
==============================================================================
--- karaf/trunk/main/src/main/java/org/osgi/framework/hooks/service/package-info.java (added)
+++ karaf/trunk/main/src/main/java/org/osgi/framework/hooks/service/package-info.java Thu Jan 5 14:16:33 2012
@@ -0,0 +1,32 @@
+/*
+ * Copyright (c) OSGi Alliance (2010). All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Framework Service Hooks Package Version 1.1.
+ *
+ * <p>
+ * Bundles wishing to use this package must list the package in the
+ * Import-Package header of the bundle's manifest.
+ *
+ * <p>
+ * Example import for consumers using the API in this package:
+ * <p>
+ * {@code Import-Package: org.osgi.framework.hooks.service; version="[1.1,2.0)"}
+ *
+ * @version $Id: 85e3128f3e46c843539b124c9adc53da34cb3e0f $
+ */
+
+package org.osgi.framework.hooks.service;
Added: karaf/trunk/main/src/main/java/org/osgi/framework/hooks/service/packageinfo
URL: http://svn.apache.org/viewvc/karaf/trunk/main/src/main/java/org/osgi/framework/hooks/service/packageinfo?rev=1227602&view=auto
==============================================================================
--- karaf/trunk/main/src/main/java/org/osgi/framework/hooks/service/packageinfo (added)
+++ karaf/trunk/main/src/main/java/org/osgi/framework/hooks/service/packageinfo Thu Jan 5 14:16:33 2012
@@ -0,0 +1 @@
+version 1.1
Added: karaf/trunk/main/src/main/java/org/osgi/framework/hooks/weaving/WeavingException.java
URL: http://svn.apache.org/viewvc/karaf/trunk/main/src/main/java/org/osgi/framework/hooks/weaving/WeavingException.java?rev=1227602&view=auto
==============================================================================
--- karaf/trunk/main/src/main/java/org/osgi/framework/hooks/weaving/WeavingException.java (added)
+++ karaf/trunk/main/src/main/java/org/osgi/framework/hooks/weaving/WeavingException.java Thu Jan 5 14:16:33 2012
@@ -0,0 +1,51 @@
+/*
+ * Copyright (c) OSGi Alliance (2010). All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.osgi.framework.hooks.weaving;
+
+/**
+ * A weaving exception used to indicate that the class load should be failed but
+ * the weaving hook must not be blacklisted by the framework.
+ *
+ * <p>
+ * This exception conforms to the general purpose exception chaining mechanism.
+ *
+ * @version $Id: eb38b85f6ed66ec445fb2f0ee7143df021327a9a $
+ */
+
+public class WeavingException extends RuntimeException {
+ private static final long serialVersionUID = 1L;
+
+ /**
+ * Creates a {@code WeavingException} with the specified message and
+ * exception cause.
+ *
+ * @param msg The associated message.
+ * @param cause The cause of this exception.
+ */
+ public WeavingException(String msg, Throwable cause) {
+ super(msg, cause);
+ }
+
+ /**
+ * Creates a {@code WeavingException} with the specified message.
+ *
+ * @param msg The message.
+ */
+ public WeavingException(String msg) {
+ super(msg);
+ }
+}
Added: karaf/trunk/main/src/main/java/org/osgi/framework/hooks/weaving/WeavingHook.java
URL: http://svn.apache.org/viewvc/karaf/trunk/main/src/main/java/org/osgi/framework/hooks/weaving/WeavingHook.java?rev=1227602&view=auto
==============================================================================
--- karaf/trunk/main/src/main/java/org/osgi/framework/hooks/weaving/WeavingHook.java (added)
+++ karaf/trunk/main/src/main/java/org/osgi/framework/hooks/weaving/WeavingHook.java Thu Jan 5 14:16:33 2012
@@ -0,0 +1,63 @@
+/*
+ * Copyright (c) OSGi Alliance (2010). All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.osgi.framework.hooks.weaving;
+
+/**
+ * OSGi Framework Weaving Hook Service.
+ *
+ * <p>
+ * Bundles registering this service will be called during framework class
+ * loading operations. Weaving hook services are called when a class is being
+ * loaded by the framework and have an opportunity to transform the class file
+ * bytes that represents the class being loaded. Weaving hooks may also ask the
+ * framework to wire in additional dynamic imports to the bundle.
+ *
+ * <p>
+ * When a class is being loaded, the framework will create a {@link WovenClass}
+ * object for the class and pass it to each registered weaving hook service for
+ * possible modification. The first weaving hook called will see the original
+ * class file bytes. Subsequently called weaving hooks will see the class file
+ * bytes as modified by previously called weaving hooks.
+ *
+ * @ThreadSafe
+ * @version $Id: d1985029024baba2db1c56aab1e06ee953fd6365 $
+ */
+
+public interface WeavingHook {
+ /**
+ * Weaving hook method.
+ *
+ * This method can modify the specified woven class object to weave the
+ * class being defined.
+ *
+ * <p>
+ * If this method throws any exception, the framework must log the exception
+ * and fail the class load in progress. This weaving hook service must be
+ * blacklisted by the framework and must not be called again. The
+ * blacklisting of this weaving hook service must expire when this weaving
+ * hook service is unregistered. However, this method can throw a
+ * {@link WeavingException} to deliberately fail the class load in progress
+ * without being blacklisted by the framework.
+ *
+ * @param wovenClass The {@link WovenClass} object that represents the data
+ * that will be used to define the class.
+ * @throws WeavingException If this weaving hook wants to deliberately fail
+ * the class load in progress without being blacklisted by the
+ * framework
+ */
+ public void weave(WovenClass wovenClass);
+}
Added: karaf/trunk/main/src/main/java/org/osgi/framework/hooks/weaving/WovenClass.java
URL: http://svn.apache.org/viewvc/karaf/trunk/main/src/main/java/org/osgi/framework/hooks/weaving/WovenClass.java?rev=1227602&view=auto
==============================================================================
--- karaf/trunk/main/src/main/java/org/osgi/framework/hooks/weaving/WovenClass.java (added)
+++ karaf/trunk/main/src/main/java/org/osgi/framework/hooks/weaving/WovenClass.java Thu Jan 5 14:16:33 2012
@@ -0,0 +1,157 @@
+/*
+ * Copyright (c) OSGi Alliance (2010, 2011). All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.osgi.framework.hooks.weaving;
+
+import java.security.ProtectionDomain;
+import java.util.List;
+
+import org.osgi.framework.wiring.BundleWiring;
+
+/**
+ * A class being woven.
+ *
+ * This object represents a class being woven and is passed to each
+ * {@link WeavingHook} for possible modification. It allows access to the most
+ * recently transformed class file bytes and to any additional packages that
+ * should be added to the bundle as dynamic imports.
+ *
+ * <p>
+ * After weaving is {@link #isWeavingComplete() complete}, this object becomes
+ * effectively immutable.
+ *
+ * @NotThreadSafe
+ * @noimplement
+ * @version $Id: c689a4c27dc39af1bf5f51338f1a8eaca1dddc1a $
+ */
+public interface WovenClass {
+
+ /**
+ * Returns the class file bytes to be used to define the
+ * {@link WovenClass#getClassName() named} class.
+ *
+ * <p>
+ * While weaving is not {@link #isWeavingComplete() complete}, this method
+ * returns a reference to the class files byte array contained in this
+ * object. After weaving is {@link #isWeavingComplete() complete}, this
+ * object becomes effectively immutable and a copy of the class file byte
+ * array is returned.
+ *
+ * @return The bytes to be used to define the
+ * {@link WovenClass#getClassName() named} class.
+ * @throws SecurityException If the caller does not have
+ * {@code AdminPermission[bundle,WEAVE]} and the Java runtime
+ * environment supports permissions.
+ */
+ public byte[] getBytes();
+
+ /**
+ * Set the class file bytes to be used to define the
+ * {@link WovenClass#getClassName() named} class. This method must not be
+ * called outside invocations of the {@link WeavingHook#weave(WovenClass)
+ * weave} method by the framework.
+ *
+ * <p>
+ * While weaving is not {@link #isWeavingComplete() complete}, this method
+ * replaces the reference to the array contained in this object with the
+ * specified array. After weaving is {@link #isWeavingComplete() complete},
+ * this object becomes effectively immutable and this method will throw an
+ * {@link IllegalStateException}.
+ *
+ * @param newBytes The new classfile that will be used to define the
+ * {@link WovenClass#getClassName() named} class. The specified array
+ * is retained by this object and the caller must not modify the
+ * specified array.
+ * @throws NullPointerException If newBytes is {@code null}.
+ * @throws IllegalStateException If weaving is {@link #isWeavingComplete()
+ * complete}.
+ * @throws SecurityException If the caller does not have
+ * {@code AdminPermission[bundle,WEAVE]} and the Java runtime
+ * environment supports permissions.
+ */
+ public void setBytes(byte[] newBytes);
+
+ /**
+ * Returns the list of dynamic import package descriptions to add to the
+ * {@link #getBundleWiring() bundle wiring} for this woven class. Changes
+ * made to the returned list will be visible to later {@link WeavingHook
+ * weaving hooks} called with this object. The returned list must not be
+ * modified outside invocations of the {@link WeavingHook#weave(WovenClass)
+ * weave} method by the framework.
+ *
+ * <p>
+ * After weaving is {@link #isWeavingComplete() complete}, this object
+ * becomes effectively immutable and the returned list will be unmodifiable.
+ *
+ * <p>
+ * If the Java runtime environment supports permissions, the caller must
+ * have {@code AdminPermission[bundle,WEAVE]} to modify the returned list.
+ *
+ * @return A list containing zero or more dynamic import package
+ * descriptions to add to the bundle wiring for this woven class.
+ * This list must throw {@code IllegalArgumentException} if a
+ * malformed dynamic import package description is added.
+ * @see "Core Specification, Dynamic Import Package, for the syntax of a dynamic import package description."
+ */
+ public List<String> getDynamicImports();
+
+ /**
+ * Returns whether weaving is complete in this woven class. Weaving is
+ * complete after the last {@link WeavingHook weaving hook} is called and
+ * the class is defined.
+ *
+ * <p>
+ * After weaving is complete, this object becomes effectively immutable.
+ *
+ * @return {@code true} weaving is complete, {@code false} otherwise.
+ */
+ public boolean isWeavingComplete();
+
+ /**
+ * Returns the fully qualified name of the class being woven.
+ *
+ * @return The fully qualified name of the class being woven.
+ */
+ public String getClassName();
+
+ /**
+ * Returns the protection domain to which the woven class will be assigned
+ * when it is defined.
+ *
+ * @return The protection domain to which the woven class will be assigned
+ * when it is defined, or {@code null} if no protection domain will
+ * be assigned.
+ */
+ public ProtectionDomain getProtectionDomain();
+
+ /**
+ * Returns the class associated with this woven class. When loading a class
+ * for the first time this method will return {@code null} until weaving is
+ * {@link #isWeavingComplete() complete}. Once weaving is complete, this
+ * method will return the class object.
+ *
+ * @return The class associated with this woven class, or {@code null} if
+ * weaving is not complete or the class definition failed.
+ */
+ public Class< ? > getDefinedClass();
+
+ /**
+ * Returns the bundle wiring whose class loader will define the woven class.
+ *
+ * @return The bundle wiring whose class loader will define the woven class.
+ */
+ public BundleWiring getBundleWiring();
+}
Added: karaf/trunk/main/src/main/java/org/osgi/framework/hooks/weaving/package-info.java
URL: http://svn.apache.org/viewvc/karaf/trunk/main/src/main/java/org/osgi/framework/hooks/weaving/package-info.java?rev=1227602&view=auto
==============================================================================
--- karaf/trunk/main/src/main/java/org/osgi/framework/hooks/weaving/package-info.java (added)
+++ karaf/trunk/main/src/main/java/org/osgi/framework/hooks/weaving/package-info.java Thu Jan 5 14:16:33 2012
@@ -0,0 +1,34 @@
+/*
+ * Copyright (c) OSGi Alliance (2010). All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Framework Weaving Hooks Package Version 1.0.
+ *
+ * <p>
+ * Bundles wishing to use this package must list the package in the
+ * Import-Package header of the bundle's manifest.
+ * </p>
+ *
+ * <p>
+ * Example import for consumers using the API in this package:
+ * </p>
+ * <p>
+ * {@code Import-Package: org.osgi.framework.hooks.weaving; version="[1.0,2.0)"}
+ * </p>
+ * @version $Id: fb1848295893f5889dc0260aecfc1437132da157 $
+ */
+
+package org.osgi.framework.hooks.weaving;
Added: karaf/trunk/main/src/main/java/org/osgi/framework/hooks/weaving/packageinfo
URL: http://svn.apache.org/viewvc/karaf/trunk/main/src/main/java/org/osgi/framework/hooks/weaving/packageinfo?rev=1227602&view=auto
==============================================================================
--- karaf/trunk/main/src/main/java/org/osgi/framework/hooks/weaving/packageinfo (added)
+++ karaf/trunk/main/src/main/java/org/osgi/framework/hooks/weaving/packageinfo Thu Jan 5 14:16:33 2012
@@ -0,0 +1 @@
+version 1.0
Added: karaf/trunk/main/src/main/java/org/osgi/framework/launch/Framework.java
URL: http://svn.apache.org/viewvc/karaf/trunk/main/src/main/java/org/osgi/framework/launch/Framework.java?rev=1227602&view=auto
==============================================================================
--- karaf/trunk/main/src/main/java/org/osgi/framework/launch/Framework.java (added)
+++ karaf/trunk/main/src/main/java/org/osgi/framework/launch/Framework.java Thu Jan 5 14:16:33 2012
@@ -0,0 +1,363 @@
+/*
+ * Copyright (c) OSGi Alliance (2008, 2010). All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.osgi.framework.launch;
+
+import java.io.InputStream;
+import java.net.URL;
+import java.util.Enumeration;
+
+import org.osgi.framework.Bundle;
+import org.osgi.framework.BundleException;
+import org.osgi.framework.Constants;
+import org.osgi.framework.FrameworkEvent;
+
+/**
+ * A Framework instance. A Framework is also known as a System Bundle.
+ *
+ * <p>
+ * Framework instances are created using a {@link FrameworkFactory}. The methods
+ * of this interface can be used to manage and control the created framework
+ * instance.
+ *
+ * @ThreadSafe
+ * @noimplement
+ * @version $Id: 2be857d06f3605a04f701b59f11e127c0f8940dc $
+ */
+public interface Framework extends Bundle {
+
+ /**
+ * Initialize this Framework. After calling this method, this Framework
+ * must:
+ * <ul>
+ * <li>Have generated a new {@link Constants#FRAMEWORK_UUID framework UUID}.
+ * </li>
+ * <li>Be in the {@link #STARTING} state.</li>
+ * <li>Have a valid Bundle Context.</li>
+ * <li>Be at start level 0.</li>
+ * <li>Have event handling enabled.</li>
+ * <li>Have reified Bundle objects for all installed bundles.</li>
+ * <li>Have registered any framework services. For example,
+ * {@code ConditionalPermissionAdmin}.</li>
+ * <li>Be {@link #adapt(Class) adaptable} to the OSGi defined types to which
+ * a system bundle can be adapted.</li>
+ * </ul>
+ *
+ * <p>
+ * This Framework will not actually be started until {@link #start() start}
+ * is called.
+ *
+ * <p>
+ * This method does nothing if called when this Framework is in the
+ * {@link #STARTING}, {@link #ACTIVE} or {@link #STOPPING} states.
+ *
+ * @throws BundleException If this Framework could not be initialized.
+ * @throws SecurityException If the Java Runtime Environment supports
+ * permissions and the caller does not have the appropriate
+ * {@code AdminPermission[this,EXECUTE]} or if there is a security
+ * manager already installed and the
+ * {@link Constants#FRAMEWORK_SECURITY} configuration property is
+ * set.
+ *
+ */
+ void init() throws BundleException;
+
+ /**
+ * Wait until this Framework has completely stopped. The {@code stop}
+ * and {@code update} methods on a Framework performs an asynchronous
+ * stop of the Framework. This method can be used to wait until the
+ * asynchronous stop of this Framework has completed. This method will only
+ * wait if called when this Framework is in the {@link #STARTING},
+ * {@link #ACTIVE}, or {@link #STOPPING} states. Otherwise it will return
+ * immediately.
+ * <p>
+ * A Framework Event is returned to indicate why this Framework has stopped.
+ *
+ * @param timeout Maximum number of milliseconds to wait until this
+ * Framework has completely stopped. A value of zero will wait
+ * indefinitely.
+ * @return A Framework Event indicating the reason this method returned. The
+ * following {@code FrameworkEvent} types may be returned by
+ * this method.
+ * <ul>
+ * <li>{@link FrameworkEvent#STOPPED STOPPED} - This Framework has
+ * been stopped. </li>
+ *
+ * <li>{@link FrameworkEvent#STOPPED_UPDATE STOPPED_UPDATE} - This
+ * Framework has been updated which has shutdown and will now
+ * restart.</li>
+ *
+ * <li> {@link FrameworkEvent#STOPPED_BOOTCLASSPATH_MODIFIED
+ * STOPPED_BOOTCLASSPATH_MODIFIED} - This Framework has been stopped
+ * and a bootclasspath extension bundle has been installed or
+ * updated. The VM must be restarted in order for the changed boot
+ * class path to take effect. </li>
+ *
+ * <li>{@link FrameworkEvent#ERROR ERROR} - The Framework
+ * encountered an error while shutting down or an error has occurred
+ * which forced the framework to shutdown. </li>
+ *
+ * <li> {@link FrameworkEvent#WAIT_TIMEDOUT WAIT_TIMEDOUT} - This
+ * method has timed out and returned before this Framework has
+ * stopped.</li>
+ * </ul>
+ * @throws InterruptedException If another thread interrupted the current
+ * thread before or while the current thread was waiting for this
+ * Framework to completely stop. The <i>interrupted status</i> of
+ * the current thread is cleared when this exception is thrown.
+ * @throws IllegalArgumentException If the value of timeout is negative.
+ */
+ FrameworkEvent waitForStop(long timeout) throws InterruptedException;
+
+ /**
+ * Start this Framework.
+ *
+ * <p>
+ * The following steps are taken to start this Framework:
+ * <ol>
+ * <li>If this Framework is not in the {@link #STARTING} state,
+ * {@link #init() initialize} this Framework.</li>
+ * <li>All installed bundles must be started in accordance with each
+ * bundle's persistent <i>autostart setting</i>. This means some bundles
+ * will not be started, some will be started with <i>eager activation</i>
+ * and some will be started with their <i>declared activation</i> policy.
+ * The start level of this Framework is moved to the start level specified
+ * by the {@link Constants#FRAMEWORK_BEGINNING_STARTLEVEL beginning start
+ * level} framework property, as described in the <i>Start Level
+ * Specification</i>. If this framework property is not specified, then the
+ * start level of this Framework is moved to start level one (1). Any
+ * exceptions that occur during bundle starting must be wrapped in a
+ * {@link BundleException} and then published as a framework event of type
+ * {@link FrameworkEvent#ERROR}</li>
+ * <li>This Framework's state is set to {@link #ACTIVE}.</li>
+ * <li>A framework event of type {@link FrameworkEvent#STARTED} is fired</li>
+ * </ol>
+ *
+ * @throws BundleException If this Framework could not be started.
+ * @throws SecurityException If the caller does not have the appropriate
+ * {@code AdminPermission[this,EXECUTE]}, and the Java Runtime
+ * Environment supports permissions.
+ * @see "Start Level Specification"
+ */
+ void start() throws BundleException;
+
+ /**
+ * Start this Framework.
+ *
+ * <p>
+ * Calling this method is the same as calling {@link #start()}. There are no
+ * start options for the Framework.
+ *
+ * @param options Ignored. There are no start options for the Framework.
+ * @throws BundleException If this Framework could not be started.
+ * @throws SecurityException If the caller does not have the appropriate
+ * {@code AdminPermission[this,EXECUTE]}, and the Java Runtime
+ * Environment supports permissions.
+ * @see #start()
+ */
+ void start(int options) throws BundleException;
+
+ /**
+ * Stop this Framework.
+ *
+ * <p>
+ * The method returns immediately to the caller after initiating the
+ * following steps to be taken on another thread.
+ * <ol>
+ * <li>This Framework's state is set to {@link #STOPPING}.</li>
+ * <li>All installed bundles must be stopped without changing each bundle's
+ * persistent <i>autostart setting</i>. The start level of this Framework is
+ * moved to start level zero (0), as described in the <i>Start Level
+ * Specification</i>. Any exceptions that occur during bundle stopping must
+ * be wrapped in a {@link BundleException} and then published as a framework
+ * event of type {@link FrameworkEvent#ERROR}</li>
+ * <li>Unregister all services registered by this Framework.</li>
+ * <li>Event handling is disabled.</li>
+ * <li>This Framework's state is set to {@link #RESOLVED}.</li>
+ * <li>All resources held by this Framework are released. This includes
+ * threads, bundle class loaders, open files, etc.</li>
+ * <li>Notify all threads that are waiting at {@link #waitForStop(long)
+ * waitForStop} that the stop operation has completed.</li>
+ * </ol>
+ * <p>
+ * After being stopped, this Framework may be discarded, initialized or
+ * started.
+ *
+ * @throws BundleException If stopping this Framework could not be
+ * initiated.
+ * @throws SecurityException If the caller does not have the appropriate
+ * {@code AdminPermission[this,EXECUTE]}, and the Java Runtime
+ * Environment supports permissions.
+ * @see "Start Level Specification"
+ */
+ void stop() throws BundleException;
+
+ /**
+ * Stop this Framework.
+ *
+ * <p>
+ * Calling this method is the same as calling {@link #stop()}. There are no
+ * stop options for the Framework.
+ *
+ * @param options Ignored. There are no stop options for the Framework.
+ * @throws BundleException If stopping this Framework could not be
+ * initiated.
+ * @throws SecurityException If the caller does not have the appropriate
+ * {@code AdminPermission[this,EXECUTE]}, and the Java Runtime
+ * Environment supports permissions.
+ * @see #stop()
+ */
+ void stop(int options) throws BundleException;
+
+ /**
+ * The Framework cannot be uninstalled.
+ *
+ * <p>
+ * This method always throws a BundleException.
+ *
+ * @throws BundleException This Framework cannot be uninstalled.
+ * @throws SecurityException If the caller does not have the appropriate
+ * {@code AdminPermission[this,LIFECYCLE]}, and the Java
+ * Runtime Environment supports permissions.
+ */
+ void uninstall() throws BundleException;
+
+ /**
+ * Stop and restart this Framework.
+ *
+ * <p>
+ * The method returns immediately to the caller after initiating the
+ * following steps to be taken on another thread.
+ * <ol>
+ * <li>Perform the steps in the {@link #stop()} method to stop this
+ * Framework.</li>
+ * <li>Perform the steps in the {@link #start()} method to start this
+ * Framework.</li>
+ * </ol>
+ *
+ * @throws BundleException If stopping and restarting this Framework could
+ * not be initiated.
+ * @throws SecurityException If the caller does not have the appropriate
+ * {@code AdminPermission[this,LIFECYCLE]}, and the Java
+ * Runtime Environment supports permissions.
+ */
+ void update() throws BundleException;
+
+ /**
+ * Stop and restart this Framework.
+ *
+ * <p>
+ * Calling this method is the same as calling {@link #update()} except that
+ * any provided InputStream is immediately closed.
+ *
+ * @param in Any provided InputStream is immediately closed before returning
+ * from this method and otherwise ignored.
+ * @throws BundleException If stopping and restarting this Framework could
+ * not be initiated.
+ * @throws SecurityException If the caller does not have the appropriate
+ * {@code AdminPermission[this,LIFECYCLE]}, and the Java
+ * Runtime Environment supports permissions.
+ */
+ void update(InputStream in) throws BundleException;
+
+ /**
+ * Returns the Framework unique identifier. This Framework is assigned the
+ * unique identifier zero (0) since this Framework is also a System Bundle.
+ *
+ * @return 0.
+ * @see Bundle#getBundleId()
+ */
+ long getBundleId();
+
+ /**
+ * Returns the Framework location identifier. This Framework is assigned the
+ * unique location "{@code System Bundle}" since this
+ * Framework is also a System Bundle.
+ *
+ * @return The string "{@code System Bundle}".
+ * @throws SecurityException If the caller does not have the appropriate
+ * {@code AdminPermission[this,METADATA]}, and the Java Runtime
+ * Environment supports permissions.
+ * @see Bundle#getLocation()
+ * @see Constants#SYSTEM_BUNDLE_LOCATION
+ */
+ String getLocation();
+
+ /**
+ * Returns the symbolic name of this Framework. The symbolic name is unique
+ * for the implementation of the framework. However, the symbolic name
+ * "{@code system.bundle}" must be recognized as an alias to
+ * the implementation-defined symbolic name since this Framework is also a
+ * System Bundle.
+ *
+ * @return The symbolic name of this Framework.
+ * @see Bundle#getSymbolicName()
+ * @see Constants#SYSTEM_BUNDLE_SYMBOLICNAME
+ */
+ String getSymbolicName();
+
+ /**
+ * Returns {@code null} as a framework implementation does not have a
+ * proper bundle from which to return entry paths.
+ *
+ * @param path Ignored.
+ * @return {@code null} as a framework implementation does not have a
+ * proper bundle from which to return entry paths.
+ */
+ Enumeration<String> getEntryPaths(String path);
+
+ /**
+ * Returns {@code null} as a framework implementation does not have a
+ * proper bundle from which to return an entry.
+ *
+ * @param path Ignored.
+ * @return {@code null} as a framework implementation does not have a
+ * proper bundle from which to return an entry.
+ */
+ URL getEntry(String path);
+
+ /**
+ * Returns {@code null} as a framework implementation does not have a proper
+ * bundle from which to return entries.
+ *
+ * @param path Ignored.
+ * @param filePattern Ignored.
+ * @param recurse Ignored.
+ * @return {@code null} as a framework implementation does not have a proper
+ * bundle from which to return entries.
+ */
+ Enumeration<URL> findEntries(String path, String filePattern,
+ boolean recurse);
+
+ /**
+ * Adapt this Framework to the specified type.
+ *
+ * <p>
+ * Adapting this Framework to the specified type may require certain checks,
+ * including security checks, to succeed. If a check does not succeed, then
+ * this Framework cannot be adapted and {@code null} is returned. If this
+ * Framework is not {@link #init() initialized}, then {@code null} is
+ * returned if the specified type is one of the OSGi defined types to which
+ * a system bundle can be adapted.
+ *
+ * @param <A> The type to which this Framework is to be adapted.
+ * @param type Class object for the type to which this Framework is to be
+ * adapted.
+ * @return The object, of the specified type, to which this Framework has
+ * been adapted or {@code null} if this Framework cannot be adapted
+ */
+ <A> A adapt(Class<A> type);
+}