You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@felix.apache.org by ri...@apache.org on 2011/04/11 23:11:59 UTC
svn commit: r1091216 [4/4] - in /felix/sandbox/rickhall/framework-r43: ./
src/main/java/org/apache/felix/framework/
src/main/java/org/apache/felix/framework/capabilityset/
src/main/java/org/apache/felix/framework/resolver/
src/main/java/org/apache/feli...
Added: felix/sandbox/rickhall/framework-r43/src/main/java/org/osgi/framework/wiring/BundleRevision.java
URL: http://svn.apache.org/viewvc/felix/sandbox/rickhall/framework-r43/src/main/java/org/osgi/framework/wiring/BundleRevision.java?rev=1091216&view=auto
==============================================================================
--- felix/sandbox/rickhall/framework-r43/src/main/java/org/osgi/framework/wiring/BundleRevision.java (added)
+++ felix/sandbox/rickhall/framework-r43/src/main/java/org/osgi/framework/wiring/BundleRevision.java Mon Apr 11 21:11:58 2011
@@ -0,0 +1,255 @@
+/*
+ * 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.wiring;
+
+import java.util.List;
+
+import org.osgi.framework.Bundle;
+import org.osgi.framework.BundleReference;
+import org.osgi.framework.Constants;
+import org.osgi.framework.Version;
+
+/**
+ * Bundle Revision. When a bundle is installed and each time a bundle is
+ * updated, a new bundle revision of the bundle is created. Since a bundle
+ * update can change the entries in a bundle, different bundle wirings for the
+ * same bundle can be associated with different bundle revisions.
+ *
+ * <p>
+ * For a bundle that has not been uninstalled, the most recent bundle revision
+ * is defined to be the current bundle revision. A bundle in the UNINSTALLED
+ * state does not have a current revision. The current bundle revision for a
+ * bundle can be obtained by calling {@link Bundle#adapt(Class) bundle.adapt}
+ * (BundleRevision.class). Since a bundle in the UNINSTALLED state does not have
+ * a current revision, adapting such a bundle returns {@code null}.
+ *
+ * <p>
+ * The framework defines name spaces for {@link #PACKAGE_NAMESPACE package},
+ * {@link #BUNDLE_NAMESPACE bundle} and {@link #HOST_NAMESPACE host}
+ * capabilities and requirements. These name spaces are defined only to express
+ * wiring information by the framework. They must not be used in
+ * {@link Constants#PROVIDE_CAPABILITY Provide-Capability} and
+ * {@link Constants#REQUIRE_CAPABILITY Require-Capability} manifest headers.
+ *
+ * @ThreadSafe
+ * @noimplement
+ * @version $Id: 139b3046ebd46c48b03dda8d36f2f9d79e2e616d $
+ */
+public interface BundleRevision extends BundleReference {
+ /**
+ * Returns the symbolic name for this bundle revision.
+ *
+ * @return The symbolic name for this bundle revision.
+ * @see Bundle#getSymbolicName()
+ */
+ String getSymbolicName();
+
+ /**
+ * Returns the version for this bundle revision.
+ *
+ * @return The version for this bundle revision, or
+ * {@link Version#emptyVersion} if this bundle revision has no
+ * version information.
+ * @see Bundle#getVersion()
+ */
+ Version getVersion();
+
+ /**
+ * Returns the capabilities declared by this bundle revision.
+ *
+ * @param namespace The name space of the declared capabilities to return or
+ * {@code null} to return the declared capabilities from all name
+ * spaces.
+ * @return A list containing a snapshot of the declared
+ * {@link BundleCapability}s, or an empty list if this bundle
+ * revision declares no capabilities in the specified name space.
+ * The list contains the declared capabilities in the order they are
+ * specified in the manifest.
+ */
+ List<BundleCapability> getDeclaredCapabilities(String namespace);
+
+ /**
+ * Returns the requirements declared by this bundle revision.
+ *
+ * @param namespace The name space of the declared requirements to return or
+ * {@code null} to return the declared requirements from all name
+ * spaces.
+ * @return A list containing a snapshot of the declared
+ * {@link BundleRequirement}s, or an empty list if this bundle
+ * revision declares no requirements in the specified name space.
+ * The list contains the declared requirements in the order they are
+ * specified in the manifest.
+ */
+ List<BundleRequirement> getDeclaredRequirements(String namespace);
+
+ /**
+ * Name space for package capabilities and requirements.
+ *
+ * <p>
+ * The name of the package is stored in the capability attribute of the same
+ * name as this name space (osgi.wiring.package). The other
+ * directives and attributes of the package, from the
+ * {@link Constants#EXPORT_PACKAGE Export-Package} manifest header, can be
+ * found in the cabability's {@link BundleCapability#getDirectives()
+ * directives} and {@link BundleCapability#getAttributes() attributes}. The
+ * {@link Constants#VERSION_ATTRIBUTE version} capability attribute must
+ * contain the {@link Version} of the package if one is specified or
+ * {@link Version#emptyVersion} if not specified. The
+ * {@link Constants#BUNDLE_SYMBOLICNAME_ATTRIBUTE bundle-symbolic-name}
+ * capability attribute must contain the
+ * {@link BundleRevision#getSymbolicName() symbolic name} of the provider if
+ * one is specified. The {@link Constants#BUNDLE_VERSION_ATTRIBUTE
+ * bundle-version} capability attribute must contain the
+ * {@link BundleRevision#getVersion() version} of the provider if one is
+ * specified or {@link Version#emptyVersion} if not specified.
+ *
+ * <p>
+ * The package capabilities provided by the system bundle, that is the
+ * bundle with id zero, must include the package specified by the
+ * {@link Constants#FRAMEWORK_SYSTEMPACKAGES} and
+ * {@link Constants#FRAMEWORK_SYSTEMPACKAGES_EXTRA} framework properties as
+ * well as any other package exported by the framework implementation.
+ *
+ * <p>
+ * A bundle revision {@link BundleRevision#getDeclaredCapabilities(String)
+ * declares} zero or more package capabilities (this is, exported packages)
+ * and {@link BundleRevision#getDeclaredRequirements(String) declares} zero
+ * or more package requirements.
+ * <p>
+ * A bundle wiring {@link BundleWiring#getCapabilities(String) provides}
+ * zero or more resolved package capabilities (that is, exported packages)
+ * and {@link BundleWiring#getRequiredWires(String) requires} zero or more
+ * resolved package requirements (that is, imported packages). The number of
+ * package wires required by a bundle wiring may change as the bundle wiring
+ * may dynamically import additional packages.
+ */
+ String PACKAGE_NAMESPACE = "osgi.wiring.package";
+
+ /**
+ * Name space for bundle capabilities and requirements.
+ *
+ * <p>
+ * The bundle symbolic name of the bundle is stored in the capability
+ * attribute of the same name as this name space (osgi.wiring.bundle).
+ * The other directives and attributes of the bundle, from the
+ * {@link Constants#BUNDLE_SYMBOLICNAME Bundle-SymbolicName} manifest
+ * header, can be found in the cabability's
+ * {@link BundleCapability#getDirectives() directives} and
+ * {@link BundleCapability#getAttributes() attributes}. The
+ * {@link Constants#BUNDLE_VERSION_ATTRIBUTE bundle-version} capability
+ * attribute must contain the {@link Version} of the bundle from the
+ * {@link Constants#BUNDLE_VERSION Bundle-Version} manifest header if one is
+ * specified or {@link Version#emptyVersion} if not specified.
+ *
+ * <p>
+ * A non-fragment revision
+ * {@link BundleRevision#getDeclaredCapabilities(String) declares} exactly
+ * one<sup>†</sup> bundle capability (that is, the bundle can be
+ * required by another bundle). A fragment revision must not declare a
+ * bundle capability.
+ *
+ * <p>
+ * A bundle wiring for a non-fragment revision
+ * {@link BundleWiring#getCapabilities(String) provides} exactly
+ * one<sup>†</sup> bundle capability (that is, the bundle can be
+ * required by another bundle) and
+ * {@link BundleWiring#getRequiredWires(String) requires} zero or more
+ * bundle capabilities (that is, requires other bundles).
+ *
+ * <p>
+ * † A bundle with no bundle symbolic name (that is, a bundle with
+ * {@link Constants#BUNDLE_MANIFESTVERSION Bundle-ManifestVersion}
+ * {@literal <} 2) must not provide a bundle capability.
+ */
+ String BUNDLE_NAMESPACE = "osgi.wiring.bundle";
+
+ /**
+ * Name space for host capabilities and requirements.
+ *
+ * <p>
+ * The bundle symbolic name of the bundle is stored in the capability
+ * attribute of the same name as this name space (osgi.wiring.host).
+ * The other directives and attributes of the bundle, from the
+ * {@link Constants#BUNDLE_SYMBOLICNAME Bundle-SymbolicName} manifest
+ * header, can be found in the cabability's
+ * {@link BundleCapability#getDirectives() directives} and
+ * {@link BundleCapability#getAttributes() attributes}. The
+ * {@link Constants#BUNDLE_VERSION_ATTRIBUTE bundle-version} capability
+ * attribute must contain the {@link Version} of the bundle from the
+ * {@link Constants#BUNDLE_VERSION Bundle-Version} manifest header if one is
+ * specified or {@link Version#emptyVersion} if not specified.
+ *
+ * <p>
+ * A non-fragment revision
+ * {@link BundleRevision#getDeclaredCapabilities(String) declares} zero or
+ * one<sup>†</sup> host capability if the bundle
+ * {@link Constants#FRAGMENT_ATTACHMENT_DIRECTIVE allows fragments to be
+ * attached}. A fragment revision must
+ * {@link BundleRevision#getDeclaredRequirements(String) declare} exactly
+ * one host requirement.
+ *
+ * <p>
+ * A bundle wiring for a non-fragment revision
+ * {@link BundleWiring#getCapabilities(String) provides} zero or
+ * one<sup>†</sup> host capability if the bundle
+ * {@link Constants#FRAGMENT_ATTACHMENT_DIRECTIVE allows fragments to be
+ * attached}. A bundle wiring for a fragment revision
+ * {@link BundleWiring#getRequiredWires(String) requires} a host capability
+ * for each host to which it is attached.
+ *
+ * <p>
+ * † A bundle with no bundle symbolic name (that is, a bundle with
+ * {@link Constants#BUNDLE_MANIFESTVERSION Bundle-ManifestVersion}
+ * {@literal <} 2) must not provide a host capability.
+ */
+ String HOST_NAMESPACE = "osgi.wiring.host";
+
+ /**
+ * Returns the special types of this bundle revision. The bundle revision
+ * type values are:
+ * <ul>
+ * <li>{@link #TYPE_FRAGMENT}
+ * </ul>
+ *
+ * A bundle revision may be more than one type at a time. A type code is
+ * used to identify the bundle revision type for future extendability.
+ *
+ * <p>
+ * If this bundle revision is not one or more of the defined types then 0 is
+ * returned.
+ *
+ * @return The special types of this bundle revision. The type values are
+ * ORed together.
+ */
+ int getTypes();
+
+ /**
+ * Bundle revision type indicating the bundle revision is a fragment.
+ *
+ * @see #getTypes()
+ */
+ int TYPE_FRAGMENT = 0x00000001;
+
+ /**
+ * Returns the bundle wiring which is using this bundle revision.
+ *
+ * @return The bundle wiring which is using this bundle revision or
+ * {@code null} if no bundle wiring is using this bundle revision.
+ * @see BundleWiring#getRevision()
+ */
+ BundleWiring getWiring();
+}
Added: felix/sandbox/rickhall/framework-r43/src/main/java/org/osgi/framework/wiring/BundleWire.java
URL: http://svn.apache.org/viewvc/felix/sandbox/rickhall/framework-r43/src/main/java/org/osgi/framework/wiring/BundleWire.java?rev=1091216&view=auto
==============================================================================
--- felix/sandbox/rickhall/framework-r43/src/main/java/org/osgi/framework/wiring/BundleWire.java (added)
+++ felix/sandbox/rickhall/framework-r43/src/main/java/org/osgi/framework/wiring/BundleWire.java Mon Apr 11 21:11:58 2011
@@ -0,0 +1,72 @@
+/*
+ * 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.wiring;
+
+/**
+ * A wire connecting a {@link BundleCapability} to a {@link BundleRequirement}.
+ *
+ * @ThreadSafe
+ * @noimplement
+ * @version $Id: 4f936a84065762ec3267a44f86ae01b0150e44ce $
+ */
+public interface BundleWire {
+ /**
+ * Returns the {@link BundleCapability} for this wire.
+ *
+ * @return The {@link BundleCapability} for this wire.
+ */
+ BundleCapability getCapability();
+
+ /**
+ * Return the {@link BundleRequirement} for this wire.
+ *
+ * @return The {@link BundleRequirement} for this wire.
+ */
+ BundleRequirement getRequirement();
+
+ /**
+ * Returns the bundle wiring {@link BundleWiring#getProvidedWires(String)
+ * providing} the {@link #getCapability() capability}.
+ *
+ * <p>
+ * The bundle revision referenced by the returned bundle wiring may differ
+ * from the bundle revision reference by the {@link #getCapability()
+ * capability}.
+ *
+ * @return The bundle wiring providing the capability. If the bundle wiring
+ * providing the capability is not {@link BundleWiring#isInUse() in
+ * use}, {@code null} will be returned.
+ */
+ BundleWiring getProviderWiring();
+
+ /**
+ * Returns the bundle wiring who
+ * {@link BundleWiring#getRequiredWires(String) requires} the
+ * {@link #getCapability() capability}.
+ *
+ * <p>
+ * The bundle revision referenced by the returned bundle wiring may differ
+ * from the bundle revision reference by the {@link #getRequirement()
+ * requirement}.
+ *
+ * @return The bundle wiring whose requirement is wired to the capability.
+ * If the bundle wiring requiring the capability is not
+ * {@link BundleWiring#isInUse() in use}, {@code null} will be
+ * returned.
+ */
+ BundleWiring getRequirerWiring();
+}
Added: felix/sandbox/rickhall/framework-r43/src/main/java/org/osgi/framework/wiring/BundleWiring.java
URL: http://svn.apache.org/viewvc/felix/sandbox/rickhall/framework-r43/src/main/java/org/osgi/framework/wiring/BundleWiring.java?rev=1091216&view=auto
==============================================================================
--- felix/sandbox/rickhall/framework-r43/src/main/java/org/osgi/framework/wiring/BundleWiring.java (added)
+++ felix/sandbox/rickhall/framework-r43/src/main/java/org/osgi/framework/wiring/BundleWiring.java Mon Apr 11 21:11:58 2011
@@ -0,0 +1,344 @@
+/*
+ * 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.wiring;
+
+import java.net.URL;
+import java.util.Collection;
+import java.util.List;
+
+import org.osgi.framework.Bundle;
+import org.osgi.framework.BundleReference;
+
+/**
+ * A wiring for a bundle. Each time a bundle is resolved, a new bundle wiring
+ * for the bundle is created. A bundle wiring is associated with a bundle
+ * revision and represents the dependencies with other bundle wirings.
+ *
+ * <p>
+ * The bundle wiring for a bundle is the {@link #isCurrent() current} bundle
+ * wiring if it is the most recent bundle wiring for the current bundle
+ * revision. A bundle wiring is {@link #isInUse() in use} if it is the current
+ * bundle wiring or if some other in use bundle wiring is dependent upon it. For
+ * example, another bundle wiring is wired to a capability provided by the
+ * bundle wiring. An in use bundle wiring for a non-fragment bundle has a class
+ * loader. All bundles with non-current, in use bundle wirings are considered
+ * removal pending. Once a bundle wiring is no longer in use, it is considered
+ * stale and is discarded by the framework.
+ *
+ * <p>
+ * The current bundle wiring for a bundle can be obtained by calling
+ * {@link Bundle#adapt(Class) bundle.adapt}(BundleWiring.class). A bundle in the
+ * INSTALLED or UNINSTALLED state does not have a current wiring, adapting such
+ * a bundle returns {@code null}.
+ *
+ * @ThreadSafe
+ * @noimplement
+ * @version $Id: 58b8ec3bb9649387d4ccba1070f034f217d06ea2 $
+ */
+public interface BundleWiring extends BundleReference {
+ /**
+ * Returns {@code true} if this bundle wiring is the current bundle wiring.
+ * The bundle wiring for a bundle is the current bundle wiring if it is the
+ * most recent bundle wiring for the current bundle revision. All bundles
+ * with non-current, in use bundle wirings are considered
+ * {@link FrameworkWiring#getRemovalPendingBundles() removal pending}.
+ *
+ * @return {@code true} if this bundle wiring is the current bundle wiring;
+ * {@code false} otherwise.
+ */
+ boolean isCurrent();
+
+ /**
+ * Returns {@code true} if this bundle wiring is in use. A bundle wiring is
+ * in use if it is the {@link #isCurrent() current} wiring or if some other
+ * in use bundle wiring is dependent upon it. Once a bundle wiring is no
+ * longer in use, it is considered stale and is discarded by the framework.
+ *
+ * @return {@code true} if this bundle wiring is in use; {@code false}
+ * otherwise.
+ */
+ boolean isInUse();
+
+ /**
+ * Returns the capabilities provided by this bundle wiring.
+ *
+ * <p>
+ * A capability may not be required by any bundle wiring and thus there may
+ * be no {@link #getProvidedWires(String) wires} for the capability.
+ *
+ * <p>
+ * A bundle wiring for a non-fragment revision provides a subset of the
+ * declared capabilities from the bundle revision and all attached fragment
+ * revisions. Not all declared capabilities may be provided since some may
+ * be discarded. For example, if a package is declared to be exported and
+ * import, only one is selected and the other is discarded.
+ *
+ * @param namespace The name space of the capabilities to return or
+ * {@code null} to return the capabilities from all name spaces.
+ * @return A list containing a snapshot of the {@link BundleCapability}s, or
+ * an empty list if this bundle wiring provides no capabilities in
+ * the specified name space. If this bundle wiring is not
+ * {@link #isInUse() in use}, {@code null} will be returned. For a
+ * given name space, the list contains the wires in the order the
+ * capabilities were specified in the manifests of the
+ * {@link #getRevision() bundle revision} and the attached fragments
+ * of this bundle wiring. There is no ordering defined between
+ * capabilities in different name spaces.
+ */
+ List<BundleCapability> getCapabilities(String namespace);
+
+ /**
+ * Returns the requirements of this bundle wiring.
+ *
+ * <p>
+ * A bundle wiring for a non-fragment revision has a subset of the declared
+ * requirements from the bundle revision and all attached fragment
+ * revisions. Not all declared requirements may be present since some may be
+ * discarded. For example, if a package is declared to be optionally
+ * imported and is not actually imported, the requirement must be discarded.
+ *
+ * @param namespace The name space of the requirements to return or
+ * {@code null} to return the requirements from all name spaces.
+ * @return A list containing a snapshot of the {@link BundleRequirement}s,
+ * or an empty list if this bundle wiring uses no requirements in
+ * the specified name space. If this bundle wiring is not
+ * {@link #isInUse() in use}, {@code null} will be returned. For a
+ * given name space, the list contains the wires in the order the
+ * requirements were specified in the manifests of the
+ * {@link #getRevision() bundle revision} and the attached fragments
+ * of this bundle wiring. There is no ordering defined between
+ * requirements in different name spaces.
+ */
+ List<BundleRequirement> getRequirements(String namespace);
+
+ /**
+ * Returns the {@link BundleWire}s to the provided {@link BundleCapability
+ * capabilities} of this bundle wiring.
+ *
+ * @param namespace The name space of the capabilities for which to return
+ * wires or {@code null} to return the wires for the capabilities in
+ * all name spaces.
+ * @return A list containing a snapshot of the {@link BundleWire}s for the
+ * {@link BundleCapability capabilities} of this bundle wiring, or
+ * an empty list if this bundle wiring has no capabilities in the
+ * specified name space. If this bundle wiring is not
+ * {@link #isInUse() in use}, {@code null} will be returned. For a
+ * given name space, the list contains the wires in the order the
+ * capabilities were specified in the manifests of the
+ * {@link #getRevision() bundle revision} and the attached fragments
+ * of this bundle wiring. There is no ordering defined between
+ * capabilities in different name spaces.
+ */
+ List<BundleWire> getProvidedWires(String namespace);
+
+ /**
+ * Returns the {@link BundleWire}s to the {@link BundleRequirement
+ * requirements} in use by this bundle wiring.
+ *
+ * <p>
+ * This method may return different results if this bundle wiring adds wires
+ * to more requirements. For example, dynamically importing a package will
+ * establish a new wire to the dynamically imported package.
+ *
+ * @param namespace The name space of the requirements for which to return
+ * wires or {@code null} to return the wires for the requirements in
+ * all name spaces.
+ * @return A list containing a snapshot of the {@link BundleWire}s for the
+ * {@link BundleRequirement requirements} of this bundle wiring, or
+ * an empty list if this bundle wiring has no requirements in the
+ * specified name space. If this bundle wiring is not
+ * {@link #isInUse() in use}, {@code null} will be returned. For a
+ * given name space, the list contains the wires in the order the
+ * requirements were specified in the manifests of the
+ * {@link #getRevision() bundle revision} and the attached fragments
+ * of this bundle wiring. There is no ordering defined between
+ * requirements in different name spaces.
+ */
+ List<BundleWire> getRequiredWires(String namespace);
+
+ /**
+ * Returns the bundle revision for the bundle in this bundle wiring. Since a
+ * bundle update can change the entries in a bundle, different bundle
+ * wirings for the same bundle can have different bundle revisions.
+ *
+ * <p>
+ * The bundle object {@link BundleReference#getBundle() referenced} by the
+ * returned {@code BundleRevision} may return different information than the
+ * returned {@code BundleRevision} since the returned {@code BundleRevision}
+ * may refer to an older revision of the bundle.
+ *
+ * @return The bundle revision for this bundle wiring.
+ * @see BundleRevision#getWiring()
+ */
+ BundleRevision getRevision();
+
+ /**
+ * Returns the class loader for this bundle wiring. Since a bundle refresh
+ * creates a new bundle wiring for a bundle, different bundle wirings for
+ * the same bundle will have different class loaders.
+ *
+ * @return The class loader for this bundle wiring. If this bundle wiring is
+ * not {@link #isInUse() in use} or this bundle wiring is for a
+ * fragment revision, {@code null} will be returned.
+ * @throws SecurityException If the caller does not have the appropriate
+ * {@code RuntimePermission("getClassLoader")}, and the Java Runtime
+ * Environment supports permissions.
+ */
+ ClassLoader getClassLoader();
+
+ /**
+ * Returns entries in this bundle wiring's {@link #getRevision() bundle
+ * revision} and its attached fragment revisions. This bundle wiring's class
+ * loader is not used to search for entries. Only the contents of this
+ * bundle wiring's bundle revision and its attached fragment revisions are
+ * searched for the specified entries.
+ *
+ * <p>
+ * This method takes into account that the "contents" of this
+ * bundle wiring can have attached fragments. This "bundle space"
+ * is not a name space with unique members; the same entry name can be
+ * present multiple times. This method therefore returns a list of URL
+ * objects. These URLs can come from different JARs but have the same path
+ * name. This method can either return only entries in the specified path or
+ * recurse into subdirectories returning entries in the directory tree
+ * beginning at the specified path.
+ *
+ * <p>
+ * Note: Jar and zip files are not required to include directory entries.
+ * URLs to directory entries will not be returned if the bundle contents do
+ * not contain directory entries.
+ *
+ * @param path The path name in which to look. The path is always relative
+ * to the root of this bundle wiring and may begin with
+ * "/". A path value of "/" indicates the root of
+ * this bundle wiring.
+ * @param filePattern The file name pattern for selecting entries in the
+ * specified path. The pattern is only matched against the last
+ * element of the entry path. If the entry is a directory then the
+ * trailing "/" is not used for pattern matching. Substring
+ * matching is supported, as specified in the Filter specification,
+ * using the wildcard character ("*"). If {@code null} is
+ * specified, this is equivalent to "*" and matches all
+ * files.
+ * @param options The options for listing resource names. See
+ * {@link #FINDENTRIES_RECURSE}. The method must ignore unrecognized
+ * options.
+ * @return An unmodifiable list of URL objects for each matching entry, or
+ * an empty list if no matching entry could be found, if this bundle
+ * wiring is for a fragment revision or if the caller does not have
+ * the appropriate {@code AdminPermission[bundle,RESOURCE]} and the
+ * Java Runtime Environment supports permissions. The list is
+ * ordered such that entries from the {@link #getRevision() bundle
+ * revision} are returned first followed by the entries from
+ * attached fragment revisions in attachment order. If this bundle
+ * wiring is not {@link #isInUse() in use}, {@code null} must be
+ * returned.
+ * @see Bundle#findEntries(String, String, boolean)
+ */
+ List<URL> findEntries(String path, String filePattern, int options);
+
+ /**
+ * The find entries operation must recurse into subdirectories.
+ *
+ * <p>
+ * This bit may be set when calling
+ * {@link #findEntries(String, String, int)} to specify the result must
+ * include the matching entries from the specified path and its
+ * subdirectories. If this bit is not set, then the result must only include
+ * matching entries from the specified path.
+ *
+ * @see #findEntries(String, String, int)
+ */
+ int FINDENTRIES_RECURSE = 0x00000001;
+
+ /**
+ * Returns the names of resources visible to this bundle wiring's
+ * {@link #getClassLoader() class loader}. The returned names can be used to
+ * access the resources via this bundle wiring's class loader.
+ *
+ * <ul>
+ * <li>Only the resource names for resources in bundle wirings will be
+ * returned. The names of resources visible to a bundle wiring's parent
+ * class loader, such as the bootstrap class loader, must not be included in
+ * the result.
+ * <li>Only established wires will be examined for resources. This method
+ * must not cause new wires for dynamic imports to be established.
+ * </ul>
+ *
+ * @param path The path name in which to look. The path is always relative
+ * to the root of this bundle wiring's class loader and may begin
+ * with "/". A path value of "/" indicates the
+ * root of this bundle wiring's class loader.
+ * @param filePattern The file name pattern for selecting resource names in
+ * the specified path. The pattern is only matched against the last
+ * element of the resource path. If the resource is a directory then
+ * the trailing "/" is not used for pattern matching.
+ * Substring matching is supported, as specified in the Filter
+ * specification, using the wildcard character ("*"). If
+ * {@code null} is specified, this is equivalent to "*" and
+ * matches all files.
+ * @param options The options for listing resource names. See
+ * {@link #LISTRESOURCES_LOCAL} and {@link #LISTRESOURCES_RECURSE}.
+ * This method must ignore unrecognized options.
+ * @return An unmodifiable collection of resource names for each matching
+ * resource, or an empty collection if no matching resource could be
+ * found, if this bundle wiring is for a fragment revision or if the
+ * caller does not have the appropriate
+ * {@code AdminPermission[bundle,RESOURCE]} and the Java Runtime
+ * Environment supports permissions. The collection is unordered and
+ * must contain no duplicate resource names. If this bundle wiring
+ * is not {@link #isInUse() in use}, {@code null} must be returned.
+ */
+ Collection<String> listResources(String path, String filePattern,
+ int options);
+
+ /**
+ * The list resource names operation must recurse into subdirectories.
+ *
+ * <p>
+ * This bit may be set when calling
+ * {@link #listResources(String, String, int)} to specify the result must
+ * include the names of matching resources from the specified path and its
+ * subdirectories. If this bit is not set, then the result must only include
+ * names of matching resources from the specified path.
+ *
+ * @see #listResources(String, String, int)
+ */
+ int LISTRESOURCES_RECURSE = 0x00000001;
+
+ /**
+ * The list resource names operation must limit the result to the names of
+ * matching resources contained in this bundle wiring's
+ * {@link #getRevision() bundle revision} and its attached fragment
+ * revisions. The result must not include resource names for resources in
+ * {@link BundleRevision#PACKAGE_NAMESPACE package} names which are
+ * {@link #getRequiredWires(String) imported} by this wiring.
+ *
+ * <p>
+ * This bit may be set when calling
+ * {@link #listResources(String, String, int)} to specify the result must
+ * only include the names of matching resources contained in this bundle
+ * wiring's bundle revision and its attached fragment revisions. If this bit
+ * is not set, then the result must include the names of matching resources
+ * reachable from this bundle wiring's class loader which may include the
+ * names of matching resources contained in imported packages and required
+ * bundles.
+ *
+ * @see #listResources(String, String, int)
+ */
+ int LISTRESOURCES_LOCAL = 0x00000002;
+}