001    /*
002     * Copyright (c) OSGi Alliance (2000, 2008). All Rights Reserved.
003     *
004     * Licensed under the Apache License, Version 2.0 (the "License");
005     * you may not use this file except in compliance with the License.
006     * You may obtain a copy of the License at
007     *
008     *      http://www.apache.org/licenses/LICENSE-2.0
009     *
010     * Unless required by applicable law or agreed to in writing, software
011     * distributed under the License is distributed on an "AS IS" BASIS,
012     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013     * See the License for the specific language governing permissions and
014     * limitations under the License.
015     */
016    package org.osgi.service.device;
017    
018    import java.io.IOException;
019    import java.io.InputStream;
020    import java.util.Dictionary;
021    
022    /**
023     * A Driver Locator service can find and load device driver bundles given a
024     * property set. Each driver is represented by a unique <code>DRIVER_ID</code>.
025     * <p>
026     * Driver Locator services provide the mechanism for dynamically downloading new
027     * device driver bundles into an OSGi environment. They are supplied by
028     * providers and encapsulate all provider-specific details related to the
029     * location and acquisition of driver bundles.
030     * 
031     * @version $Revision: 5654 $
032     * @see Driver
033     * @ThreadSafe
034     */
035    public interface DriverLocator {
036            /**
037             * Returns an array of <code>DRIVER_ID</code> strings of drivers capable of
038             * attaching to a device with the given properties.
039             * 
040             * <p>
041             * The property keys in the specified <code>Dictionary</code> objects are
042             * case-insensitive.
043             * 
044             * @param props the properties of the device for which a driver is sought
045             * @return array of driver <code>DRIVER_ID</code> strings of drivers capable
046             *         of attaching to a Device service with the given properties, or
047             *         <code>null</code> if this Driver Locator service does not know of
048             *         any such drivers
049             */
050            public String[] findDrivers(Dictionary props);
051    
052            /**
053             * Get an <code>InputStream</code> from which the driver bundle providing a
054             * driver with the giving <code>DRIVER_ID</code> can be installed.
055             * 
056             * @param id the <code>DRIVER_ID</code> of the driver that needs to be
057             *        installed.
058             * @return An <code>InputStream</code> object from which the driver bundle
059             *         can be installed or <code>null</code> if the driver with the
060             *         given ID cannot be located
061             * @throws java.io.IOException the input stream for the bundle cannot be
062             *         created
063             */
064            public InputStream loadDriver(String id) throws IOException;
065    }