/*
 * Copyright (c) OSGi Alliance (2008). 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 $Revision$
 */

public interface ListenerHook {
	/**
	 * Added listeners hook method. This method is called to provide the hook
	 * implementation with information on the current service listeners. This
	 * method will be called immediately after registration of this hook to
	 * provide the current collection of service listeners which had been added
	 * prior to the hook being registered. This method will also be called as
	 * service listeners are added while this hook is registered.
	 * 
	 * @param listeners A collection of {@link ListenerInfo}s for service
	 *        listeners which are now listening to service events. Attempting to
	 *        add to or remove from the collection will result in an
	 *        <code>UnsupportedOperationException</code>. The collection is not
	 *        synchronized.
	 */
	void added(Collection/* <? extends ListenerInfo> */listeners);

	/**
	 * Removed listeners hook method. This method is called to provide the hook
	 * implementation with information on 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 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</code>. The collection is
	 *        not synchronized.
	 */
	void removed(Collection/* <? extends 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
	 */
	public interface ListenerInfo {
		/**
		 * Return the context of the bundle which added the listener.
		 * 
		 * @return The context of the bundle which added the listener.
		 */
		public 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</code> if the listener was added without a
		 *         filter.
		 */
		public String getFilter();
	}
}

@@ -1098,27 +1098,27 @@
 tion on 
-the current
+newly added
  service
@@ -1159,16 +1159,88 @@
 e called
+ as service listeners are added while this hook is%0A%09 * registered. Also,
  immedia
@@ -1275,23 +1275,51 @@
 his hook
+,
  t
-o
+his
 %0A%09 *
+ method will be called to
  provide
@@ -1344,32 +1344,36 @@
 ction of service
+%0A%09 *
  listeners which
@@ -1387,20 +1387,16 @@
 en added
-%0A%09 *
  prior t
@@ -1427,106 +1427,8 @@
 red.
- This method will also be called as%0A%09 * service listeners are added while this hook is registered.
 %0A%09 *
@@ -1484,39 +1484,43 @@
 tenerInfo%7Ds for 
-service
+newly added
 %0A%09 *        list
@@ -1507,32 +1507,40 @@
 dded%0A%09 *        
+service 
 listeners which 
@@ -1575,16 +1575,27 @@
  events.
+%0A%09 *       
  Attempt
@@ -1600,27 +1600,16 @@
 pting to
-%0A%09 *       
  add to 
@@ -1652,19 +1652,16 @@
 esult in
- an
 %0A%09 *    
@@ -1664,16 +1664,19 @@
         
+an 
 %3Ccode%3EUn
@@ -1728,20 +1728,16 @@
 ction is
- not
 %0A%09 *    
@@ -1740,16 +1740,20 @@
         
+not 
 synchron
@@ -1949,16 +1949,22 @@
 tion on 
+newly 
 removed 
@@ -1990,19 +1990,19 @@
 This
+%0A%09 *
  method
-%0A%09 *
  wil
@@ -2149,23 +2149,29 @@
 o%7Ds for 
-service
+newly removed
 %0A%09 *    
@@ -2174,16 +2174,24 @@
         
+service 
 listener

improve javadoc