ServiceFactory.java

///*
// * Copyright (c) OSGi Alliance (2000, 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;
//
///**
// * Allows services to provide customized service objects in the OSGi
// * environment.
// * <p>
// * <p>
// * When registering a service, a <code>ServiceFactory</code> object can be
// * used instead of a service object, so that the bundle developer can gain
// * control of the specific service object granted to a bundle that is using the
// * service.
// * <p>
// * <p>
// * When this happens, the
// * <code>BundleContext.getService(ServiceReference)</code> method calls the
// * <code>ServiceFactory.getService</code> method to create a service object
// * specifically for the requesting bundle. The service object returned by the
// * <code>ServiceFactory</code> is cached by the Framework until the bundle
// * releases its use of the service.
// * <p>
// * <p>
// * When the bundle's use count for the service equals zero (including the bundle
// * stopping or the service being unregistered), the
// * <code>ServiceFactory.ungetService</code> method is called.
// * <p>
// * <p>
// * <code>ServiceFactory</code> objects are only used by the Framework and are
// * not made available to other bundles in the OSGi environment. The Framework
// * may concurrently call a <code>ServiceFactory</code>.
// *
// * @version $Revision: 5967 $
// * @see BundleContext#getService
// */
//
//public interface ServiceFactory {
//    /**
//     * Creates a new service object.
//     * <p>
//     * <p>
//     * The Framework invokes this method the first time the specified
//     * <code>bundle</code> requests a service object using the
//     * <code>BundleContext.getService(ServiceReference)</code> method. The
//     * service factory can then return a specific service object for each
//     * bundle.
//     * <p>
//     * <p>
//     * The Framework caches the value returned (unless it is <code>null</code>),
//     * and will return the same service object on any future call to
//     * <code>BundleContext.getService</code> for the same bundle. This means the
//     * Framework must not allow this method to be concurrently called for the
//     * same bundle.
//     * <p>
//     * <p>
//     * The Framework will check if the returned service object is an instance of
//     * all the classes named when the service was registered. If not, then
//     * <code>null</code> is returned to the bundle.
//     *
//     * @param bundle       The bundle using the service.
//     * @param registration The <code>ServiceRegistration</code> object for the
//     *                     service.
//     * @return A service object that <strong>must</strong> be an instance of all
//     * the classes named when the service was registered.
//
//     */
//    Object getService(Bundle bundle, ServiceRegistration registration);
//
//    /**
//     * Releases a service object.
//     * <p>
//     * <p>
//     * The Framework invokes this method when a service has been released by a
//     * bundle. The service object may then be destroyed.
//     *
//     * @param bundle       The bundle releasing the service.
//     * @param registration The <code>ServiceRegistration</code> object for the
//     *                     service.
//     * @param service      The service object returned by a previous call to the
//     *                     <code>ServiceFactory.getService</code> method.
//     * @see BundleContext#ungetService
//     */
//    void ungetService(Bundle bundle, ServiceRegistration registration,
//                      Object service);
//}