/*
 * 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;

import java.util.List;

import org.osgi.framework.Bundle;
import org.osgi.framework.BundleReference;

/**
 * The {@link BundleRevision bundle revisions} of a bundle. When a bundle is
 * installed and each time a bundle is updated, a new bundle revision of the
 * bundle is created. The current bundle revision is the most recent bundle
 * revision. An in use bundle revision is associated with an
 * {@link BundleWiring#isInUse() in use} {@link BundleWiring}. Only the current
 * bundle revision and all in use bundle revisions are returned.
 * 
 * <p>
 * The bundle revisions for a bundle can be obtained by calling
 * {@link Bundle#adapt(Class) bundle.adapt}({@link BundleRevisions}.class).
 * {@link #getRevisions()} on the bundle.
 * 
 * @ThreadSafe
 * @noimplement
 * @version $Id$
 */
public interface BundleRevisions extends BundleReference {
	/**
	 * Return the bundle revisions for the {@link BundleReference#getBundle()
	 * referenced} bundle.
	 * 
	 * <p>
	 * The result is a list of the current bundle revision and the in use bundle
	 * revisions. The list is ordered in reverse chronological order such that
	 * the first item is the current bundle revision and last item is the oldest
	 * in use bundle revision.
	 * 
	 * <p>
	 * Generally the list will have at least one bundle revision for the bundle:
	 * the current bundle revision. However, for an uninstalled bundle with no
	 * in use bundle revisions, the list will be empty.
	 * 
	 * @return A list containing a snapshot of the {@link BundleRevision}s for
	 *         the referenced bundle.
	 */
	List<BundleRevision> getRevisions();
}

@@ -943,64 +943,193 @@
 ed. 
-The current bundle revision is the most recent bundle%0A *
+For a bundle that has not been uninstalled, the most%0A * recent bundle revision is defined to be the current bundle revision. A bundle%0A * in the UNINSTALLED state does not have a current
  rev
@@ -1143,32 +1143,35 @@
 An in use bundle
+%0A *
  revision is ass
@@ -1185,19 +1185,16 @@
  with an
-%0A *
  %7B@link 
@@ -1223,16 +1223,19 @@
  in use%7D
+%0A *
  %7B@link 
@@ -1253,14 +1253,9 @@
 g%7D. 
-Only t
+T
 he c
@@ -1260,19 +1260,16 @@
  current
-%0A *
  bundle 
@@ -1280,16 +1280,34 @@
 sion
+, if there is one,
  and all
  in 
@@ -1302,16 +1302,19 @@
  and all
+%0A *
  in use 
@@ -1794,18 +1794,26 @@
  a list 
-of
+containing
  the cur
@@ -1836,45 +1836,162 @@
 sion
- and
+, if
  the
+re
  i
-n use bundle%0A%09 * revisions.
+s%0A%09 * one, and all in use bundle revisions. The list may also contain%0A%09 * intermediate bundle revisions which are not in use.%0A%09 * %0A%09 * %3Cp%3E%0A%09 *
  The
@@ -2047,20 +2047,16 @@
 uch that
-%0A%09 *
  the fir
@@ -2057,16 +2057,20 @@
 he first
+%0A%09 *
  item is
@@ -2070,28 +2070,32 @@
 item is the 
-curr
+most rec
 ent bundle r
@@ -2129,31 +2129,24 @@
 e oldest%0A%09 *
- in use
  bundle revi
@@ -2356,20 +2356,19 @@
 he list 
-will
+may
  be empt

Clarify list of revisions returned.