bundlecontext.java

OSGI这是一个中间件,与UPNP齐名,是用于移植到嵌入式平台之上

    /**
	 * 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.
	 *
	 * <p>This method is otherwise identical to
	 * {@link #registerService(java.lang.String[], java.lang.Object,
	 * java.util.Dictionary)}and is provided as a convenience when <tt>service</tt> will only
	 * be registered under a single class name. Note that even in this case the value of the service's
	 * {@link Constants#OBJECTCLASS}property will be an array of strings, rather than just a single string.
	 *
	 * @see #registerService(java.lang.String[], java.lang.Object,
	 * java.util.Dictionary)
	 */
    public abstract ServiceRegistration registerService(String clazz,
                            Object service,
                            Dictionary properties);

    /**
	 * Returns a list of <tt>ServiceReference</tt> objects. This method returns a list of
	 * <tt>ServiceReference</tt> objects for services which implement and were registered under
	 * the specified class and match the specified filter criteria.
	 *
	 * <p>The list is valid at the time of the call to this method, however as the Framework is
	 * a very dynamic environment, services can be modified or unregistered at anytime.
	 *
	 * <p><tt>filter</tt> is used to select the registered service whose
	 * properties objects contain keys and values which satisfy the filter.
	 * See {@link Filter}for a description of the filter string syntax.
	 *
	 * <p>If <tt>filter</tt> is <tt>null</tt>, all registered services
	 * are considered to match the filter.
	 * <p>If <tt>filter</tt> cannot be parsed, an {@link InvalidSyntaxException}will
	 * be thrown with a human readable message where the filter became unparsable.
	 *
	 * <p>The following steps are required to select a service:
	 * <ol>
	 * <li>If the Java Runtime Environment supports permissions, the caller is checked for the
	 * <tt>ServicePermission</tt> to get the service with the specified class.
	 * If the caller does not have the correct permission, <tt>null</tt> is returned.
	 * <li>If the filter string is not <tt>null</tt>, the filter string is
	 * parsed and the set of registered services which satisfy the filter is
	 * produced.
	 * If the filter string is <tt>null</tt>, then all registered services
	 * are considered to satisfy the filter.
	 * <li>If <tt>clazz</tt> is not <tt>null</tt>, the set is further reduced to
	 * those services which are an <tt>instanceof</tt> and were registered under the specified class.
	 * The complete list of classes of which a service is an instance and which
	 * were specified when the service was registered is available from the
	 * service's {@link Constants#OBJECTCLASS}property.
	 * <li>An array of <tt>ServiceReference</tt> to the selected services is returned.
	 * </ol>
	 *
	 * @param clazz The class name with which the service was registered, or
	 * <tt>null</tt> for all services.
	 * @param filter The filter criteria.
	 * @return An array of <tt>ServiceReference</tt> objects, or
	 * <tt>null</tt> if no services are registered which satisfy the search.
	 * @exception InvalidSyntaxException If <tt>filter</tt> contains
	 * an invalid filter string which cannot be parsed.
	 */
    public abstract ServiceReference[] getServiceReferences(String clazz,
                                String filter)
    throws InvalidSyntaxException;

    /**
	 * Returns a <tt>ServiceReference</tt> object for a service that implements, and
	 * was registered under, the specified class.
	 *
	 * <p>This <tt>ServiceReference</tt> object is valid at the time
	 * of the call to this method, however as the Framework is a very dynamic
	 * environment, services can be modified or unregistered at anytime.
	 *
	 * <p> This method is the same as calling {@link #getServiceReferences}with a
	 * <tt>null</tt> filter string.
	 * It is provided as a convenience for when the caller is interested in any service that
	 * implements the specified class. <p>If multiple such services exist, the service
	 * with the highest ranking (as specified in its {@link Constants#SERVICE_RANKING}property) is
	 * returned.
	 * <p>If there is a tie in ranking, the service with the lowest
	 * service ID (as specified in its {@link Constants#SERVICE_ID}property); that is,
	 * the service that was registered first is returned.
	 *
	 * @param clazz The class name with which the service was registered.
	 * @return A <tt>ServiceReference</tt> object, or <tt>null</tt>
	 * if no services are registered which implement the named class.
	 * @see #getServiceReferences
	 */
    public abstract ServiceReference getServiceReference(String clazz);

    /**
	 * Returns the specified service object for a service.
	 * <p>A bundle's use of a service is tracked by the bundle's use
	 * count of that service. Each time a service's service object is returned by
	 * {@link #getService}the context bundle's use count for that service
	 * is incremented by one. Each time the service is released by
	 * {@link #ungetService}the context bundle's use count for that service is decremented by one.
	 * <p>When a bundle's use count for a service drops to zero, the bundle should no longer use that service.
	 * See {@link #getBundle}for a definition of context bundle.
	 *
	 * <p>This method will always return <tt>null</tt> when the
	 * service associated with this <tt>reference</tt> has been unregistered.
	 *
	 * <p>The following steps are required to get the service object:
	 * <ol>
	 * <li>If the service has been unregistered, <tt>null</tt> is returned.
	 * <li>The context bundle's use count for this service is incremented by one.
	 * <li>If the context bundle's use count for the service is currently one and
	 * the service was registered with an object implementing the <tt>ServiceFactory</tt> interface,
	 * the {@link ServiceFactory#getService}method is called to create a service object
	 * for the context bundle.
	 * This service object is cached by the Framework.
	 * While the context bundle's use count for the service is greater than
	 * zero, subsequent calls to get the services's service object for the
	 * context bundle will return the cached service object.
	 * <br>If the service object returned by the <tt>ServiceFactory</tt> object
	 * is not an <tt>instanceof</tt> all the classes named when the service was registered or
	 * the <tt>ServiceFactory</tt> object throws an exception, <tt>null</tt> is returned and a
	 * Framework event of type {@link FrameworkEvent#ERROR}is broadcast.
	 * <li>The service object for the service is returned.
	 * </ol>
	 *
	 * @param reference A reference to the service.
	 * @return A service object for the service associated with <tt>reference</tt>,
	 * or <tt>null</tt> if the service is not registered or does not implement the classes
	 * under which it was registered in the case of a Service Factory.
	 * @exception java.lang.SecurityException If the caller does not have
	 * the <tt>ServicePermission</tt> to get the service using at least one of the named classes
	 * the service was registered under, and the Java Runtime Environment supports permissions.
	 * @exception java.lang.IllegalStateException If the context bundle has stopped.
	 * @see #ungetService
	 * @see ServiceFactory
	 */
    public abstract Object getService(ServiceReference reference);

    /**
	 * Releases the service object referenced by the specified <tt>ServiceReference</tt> object.
	 * If the context bundle's use count for the service is zero, this method
	 * returns <tt>false</tt>. Otherwise, the context bundle's use count
	 * for the service is decremented by one.
	 * See {@link #getBundle}for a definition of context bundle.
	 *
	 * <p>The service's service object should no longer be used and all references to it
	 * should be destroyed when a bundle's use count for the service drops to zero.
	 *
	 * <p>The following steps are required to unget the service object:
	 * <ol>
	 * <li>If the context bundle's use count for the service is zero or
	 * the service has been unregistered, <tt>false</tt> is returned.
	 * <li>The context bundle's use count for this service is decremented by one.
	 * <li>If the context bundle's use count for the service is currently zero and
	 * the service was registered with a <tt>ServiceFactory</tt> object, the
	 * {@link ServiceFactory#ungetService}method is called to release the service object
	 * for the context bundle.
	 * <li><tt>true</tt> is returned.
	 * </ol>
	 *
	 * @param reference A reference to the service to be released.
	 * @return <tt>false</tt> if the context bundle's use count for the
	 * service is zero or if the service has been unregistered; <tt>true</tt> otherwise.
	 * @exception java.lang.IllegalStateException If the context bundle has stopped.
	 * @see #getService
	 * @see ServiceFactory
	 */
    public abstract boolean ungetService(ServiceReference reference);

    /**
	 * Creates a <tt>File</tt> object for a file in the
	 * persistent storage area provided for the bundle by the Framework.
	 * This method will return <tt>null</tt> if the platform does not
	 * have file system support.
	 *
	 * <p>A <tt>File</tt> object for the base directory of the
	 * persistent storage area provided for the context bundle by the Framework
	 * can be obtained by calling this method with an empty string (" ")
	 * as <tt>filename</tt>.
	 * See {@link #getBundle}for a definition of context bundle.
	 *
	 * <p>If the Java Runtime Environment supports permissions,
	 * the Framework will ensure that the bundle has the <tt>java.io.FilePermission</tt> with actions
	 * <tt>read</tt>, <tt>write</tt>, <tt>delete</tt> for all files (recursively) in the
	 * persistent storage area provided for the context bundle.
	 *
	 * @param filename A relative name to the file to be accessed.
	 * @return A <tt>File</tt> object that represents the requested file or
	 * <tt>null</tt> if the platform does not have file system support.
	 * @exception java.lang.IllegalStateException If the context bundle has stopped.
	 */
    public abstract File getDataFile(String filename);

    /**
	 * Creates a <tt>Filter</tt> object. This <tt>Filter</tt> object may be used
	 * to match a <tt>ServiceReference</tt> object or a <tt>Dictionary</tt> object.
	 * See {@link Filter}for a description of the filter string syntax.
	 *
	 * <p>If the filter cannot be parsed, an {@link InvalidSyntaxException}will be thrown
	 * with a human readable message where the filter became unparsable.
	 *
	 * @param filter The filter string.
	 * @return A <tt>Filter</tt> object encapsulating the filter string.
	 * @exception InvalidSyntaxException If <tt>filter</tt> contains
	 * an invalid filter string that cannot be parsed.
	 * @exception NullPointerException If <tt>filter</tt> is null.
	 *
	 * @since 1.1
	 */
    public abstract Filter createFilter(String filter)
    throws InvalidSyntaxException;
}