bundlecontext.java

OSGI 的 源码实现,采用JAVA书写

    /**
	 * Adds the specified <tt>ServiceListener</tt> object with the specified
	 * <tt>filter</tt> to this context bundle's list of listeners. <p>See
	 * {@link #getBundle}for a definition of context bundle, and
	 * {@link Filter}for a description of the filter syntax.
	 * <tt>ServiceListener</tt> objects are notified when a service has a lifecycle state
	 * change.
	 *
	 * <p>If this context bundle's list of listeners already contains a
	 * listener <tt>l</tt> such that <tt>(l==listener)</tt>, this method
	 * replaces that listener's filter (which may be <tt>null</tt>) with the
	 * specified one (which may be <tt>null</tt>).
	 *
	 * <p>The listener is called if the filter criteria is met.
	 * To filter based upon the class of the service, the filter
	 * should reference the {@link Constants#OBJECTCLASS}property.
	 * If <tt>filter</tt> is <tt>null</tt>, all services
	 * are considered to match the filter.
	 *
	 * <p>When using a <tt>filter</tt>, it is possible that the <tt>ServiceEvent</tt>s
	 * for the complete life cycle of a service will not be delivered to
	 * the listener.
	 * For example, if the <tt>filter</tt> only matches when the property <tt>x</tt>
	 * has the value <tt>1</tt>, the listener will not be called
	 * if the service is registered with the property <tt>x</tt> not set to the value
	 * <tt>1</tt>. Subsequently, when the service is modified setting
	 * property <tt>x</tt> to the value <tt>1</tt>, the filter will match
	 * and the listener will be called with a <tt>ServiceEvent</tt>
	 * of type <tt>MODIFIED</tt>. Thus, the listener will not be called with a
	 * <tt>ServiceEvent</tt> of type <tt>REGISTERED</tt>.
	 *
	 * <p>If the Java Runtime Environment supports permissions, the
	 * <tt>ServiceListener</tt> object will be notified of a service event only
	 * if the bundle that is registering it has the <tt>ServicePermission</tt>
	 * to get the service using at least one of the named classes the service was registered under.
	 *
	 * @param listener The <tt>ServiceListener</tt> object to be added.
	 * @param filter The filter criteria.
	 *
	 * @exception InvalidSyntaxException If <tt>filter</tt> contains
	 * an invalid filter string which cannot be parsed.
	 * @exception java.lang.IllegalStateException If this context bundle has stopped.
	 *
	 * @see ServiceEvent
	 * @see ServiceListener
	 * @see ServicePermission
	 */
    public abstract void addServiceListener(ServiceListener listener,
                        String filter)
    throws InvalidSyntaxException;

    /**
	 * Adds the specified <tt>ServiceListener</tt> object to this context bundle's list of
	 * listeners.
	 *
	 * <p> This method is the same as calling <tt>BundleContext.addServiceListener(ServiceListener listener,
	 * String filter)</tt> with <tt>filter</tt> set to <tt>null</tt>.
	 *
	 * @param listener The <tt>ServiceListener</tt> object to be added.
	 * @exception java.lang.IllegalStateException If this context bundle has stopped.
	 *
	 * @see #addServiceListener(ServiceListener, String)
	 */
    public abstract void addServiceListener(ServiceListener listener);

    /**
	 * Removes the specified <tt>ServiceListener</tt> object from this context bundle's list of listeners.
	 * See {@link #getBundle}for a definition of context bundle.
	 *
	 * <p>If <tt>listener</tt> is not contained in this context bundle's list
	 * of listeners, this method does nothing.
	 *
	 * @param listener The <tt>ServiceListener</tt> to be removed.
	 * @exception java.lang.IllegalStateException If this context bundle has stopped.
	 */
    public abstract void removeServiceListener(ServiceListener listener);

    /**
	 * Adds the specified <tt>BundleListener</tt> object to this context bundle's
	 * list of listeners if not already present.
	 * See {@link #getBundle}for a definition of context bundle.
	 * BundleListener objects are notified when a bundle has a lifecycle state change.
	 *
	 * <p>If this context bundle's list of listeners already contains a
	 * listener <tt>l</tt> such that <tt>(l==listener)</tt>, this method does
	 * nothing.
	 *
	 * @param listener The <tt>BundleListener</tt> to be added.
	 * @exception java.lang.IllegalStateException If this context bundle has stopped.
	 *
	 * @see BundleEvent
	 * @see BundleListener
	 */
    public abstract void addBundleListener(BundleListener listener);

    /**
	 * Removes the specified <tt>BundleListener</tt> object from this context bundle's list of listeners.
	 * See {@link #getBundle}for a definition of context bundle.
	 *
	 * <p> If <tt>listener</tt> is not contained in this context bundle's list
	 * of listeners, this method does nothing.
	 *
	 * @param listener The <tt>BundleListener</tt> object to be removed.
	 * @exception java.lang.IllegalStateException If this context bundle has stopped.
	 */
    public abstract void removeBundleListener(BundleListener listener);

    /**
	 * Adds the specified <tt>FrameworkListener</tt> object to this context bundle's
	 * list of listeners if not already present.
	 * See {@link #getBundle}for a definition of context bundle.
	 * FrameworkListeners are notified of general Framework events.
	 *
	 * <p> If this context bundle's list of listeners already contains a
	 * listener <tt>l</tt> such that <tt>(l==listener)</tt>, this method does
	 * nothing.
	 *
	 * @param listener The <tt>FrameworkListener</tt> object to be added.
	 * @exception java.lang.IllegalStateException If this context bundle has stopped.
	 *
	 * @see FrameworkEvent
	 * @see FrameworkListener
	 */
    public abstract void addFrameworkListener(FrameworkListener listener);

    /**
	 * Removes the specified <tt>FrameworkListener</tt> object from this context
	 * bundle's list of listeners.
	 * See {@link #getBundle}for a definition of context bundle.
	 *
	 * <p> If <tt>listener</tt> is not contained in this context bundle's list
	 * of listeners, this method does nothing.
	 *
	 * @param listener The <tt>FrameworkListener</tt> object to be removed.
	 * @exception java.lang.IllegalStateException If this context bundle has stopped.
	 */
    public abstract void removeFrameworkListener(FrameworkListener listener);

    /**
	 * Registers the specified service object with the specified properties
	 * under the specified class names into the Framework.
	 * A <tt>ServiceRegistration</tt> object is returned.
	 * The <tt>ServiceRegistration</tt> object is for the private use of the
	 * bundle registering the service and should not be shared with other
	 * bundles.
	 * The registering bundle is defined to be the context bundle.
	 * See {@link #getBundle}for a definition of context bundle.
	 * Other bundles can locate the service by using either the
	 * {@link #getServiceReferences}or {@link #getServiceReference}method.
	 *
	 * <p>A bundle can register a service object that implements the
	 * {@link ServiceFactory}interface to have more flexibility in providing service objects to other
	 * bundles.
	 *
	 * <p>The following steps are required to register a service:
	 * <ol>
	 * <li>If <tt>service</tt> is not a <tt>ServiceFactory</tt>,
	 * an <tt>IllegalArgumentException</tt> is thrown if <tt>service</tt> is not an
	 * <tt>instanceof</tt> all the classes named.
	 * <li>The Framework adds these service properties to the specified
	 * <tt>Dictionary</tt> (which may be <tt>null</tt>):
	 * a property named {@link Constants#SERVICE_ID}identifying the
	 * registration number of the service, and a property named
	 * {@link Constants#OBJECTCLASS}containing all the specified
	 * classes. If any of these properties have already been specified by the
	 * registering bundle, their values will be overwritten by the Framework.
	 * <li>The service is added to the Framework service registry and may now be used by other bundles.
	 * <li>A service event of type {@link ServiceEvent#REGISTERED}is synchronously sent.
	 * <li>A <tt>ServiceRegistration</tt> object for this registration is returned.
	 * </ol>
	 *
	 * @param clazzes The class names under which the service can be located.
	 * The class names in this array will be stored in the service's properties under the key
	 * {@link Constants#OBJECTCLASS}.
	 * @param service The service object or a <tt>ServiceFactory</tt> object.
	 * @param properties The properties for this service. The keys in the properties object must
	 * all be <tt>String</tt> objects. See {@link Constants}for a list of standard service property keys.
	 * Changes should not be made to this object after calling this method.
	 * To update the service's properties the {@link ServiceRegistration#setProperties}method must be called.
	 * <tt>properties</tt> may be <tt>null</tt> if the service has no properties.
	 *
	 * @return A <tt>ServiceRegistration</tt> object for use by the bundle
	 * registering the service to update the service's properties or to unregister the service.
	 *
	 * @exception java.lang.IllegalArgumentException If one of the following is true:
	 * <ul>
	 * <li><tt>service</tt> is <tt>null</tt>.
	 * <li><tt>service</tt> is not a <tt>ServiceFactory</tt> object and is not an
	 * instance of all the named classes in <tt>clazzes</tt>.
	 * <li><tt>properties</tt> contains case variants of the same key name.
	 * </ul>
	 *
	 * @exception java.lang.SecurityException If the caller does not have the
	 * <tt>ServicePermission</tt> to register the service for all the named classes and
	 * the Java Runtime Environment supports permissions.
	 *
	 * @exception java.lang.IllegalStateException If this context bundle was stopped.
	 *
	 * @see ServiceRegistration
	 * @see ServiceFactory
	 */
    public abstract ServiceRegistration registerService(String[] clazzes,
                            Object service,
                            Dictionary properties);

    /**
	 * Registers the specified service object with the specified properties
	 * under the specified class name with the Framework.