001    /*
002     * $Header: /cvshome/build/org.osgi.service.obr/src/org/osgi/service/obr/RepositoryAdmin.java,v 1.3 2006/03/16 14:56:17 hargrave Exp $
003     *
004     * Copyright (c) OSGi Alliance (2006). All Rights Reserved.
005     *
006     * Licensed under the Apache License, Version 2.0 (the "License");
007     * you may not use this file except in compliance with the License.
008     * You may obtain a copy of the License at
009     *
010     *      http://www.apache.org/licenses/LICENSE-2.0
011     *
012     * Unless required by applicable law or agreed to in writing, software
013     * distributed under the License is distributed on an "AS IS" BASIS,
014     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015     * See the License for the specific language governing permissions and
016     * limitations under the License.
017     */
018    
019    // This document is an experimental draft to enable interoperability
020    // between bundle repositories. There is currently no commitment to 
021    // turn this draft into an official specification.  
022    package org.osgi.service.obr;
023    
024    import java.net.URL;
025    
026    /**
027     * Provides centralized access to the distributed repository.
028     * 
029     * A repository contains a set of <i>resources</i>. A resource contains a
030     * number of fixed attributes (name, version, etc) and sets of:
031     * <ol>
032     * <li>Capabilities - Capabilities provide a named aspect: a bundle, a display,
033     * memory, etc.</li>
034     * <li>Requirements - A named filter expression. The filter must be satisfied
035     * by one or more Capabilties with the given name. These capabilities can come
036     * from other resources or from the platform. If multiple resources provide the
037     * requested capability, one is selected. (### what algorithm? ###)</li>
038     * <li>Requests - Requests are like requirements, except that a request can be
039     * fullfilled by 0..n resources. This feature can be used to link to resources
040     * that are compatible with the given resource and provide extra functionality.
041     * For example, a bundle could request all its known fragments. The UI
042     * associated with the repository could list these as optional downloads.</li>
043     * 
044     * @version $Revision: 1.3 $
045     */
046    public interface RepositoryAdmin
047    {
048        /**
049         * Discover any resources that match the given filter.
050         * 
051         * This is not a detailed search, but a first scan of applicable resources.
052         * 
053         * ### Checking the capabilities of the filters is not possible because that
054         * requires a new construct in the filter.
055         * 
056         * The filter expression can assert any of the main headers of the resource.
057         * The attributes that can be checked are:
058         * 
059         * <ol>
060         * <li>name</li>
061         * <li>version (uses filter matching rules)</li>
062         * <li>description</li>
063         * <li>category</li>
064         * <li>copyright</li>
065         * <li>license</li>
066         * <li>source</li>
067         * </ol>
068         * 
069         * @param filterExpr
070         *            A standard OSGi filter
071         * @return List of resources matching the filters.
072         */
073        Resource[] discoverResources(String filterExpr);
074    
075        /**
076         * Create a resolver.
077         * 
078         * @param resource
079         * @return
080         */
081        Resolver resolver();
082    
083        /**
084         * Add a new repository to the federation.
085         * 
086         * The url must point to a repository XML file.
087         * 
088         * @param repository
089         * @return
090         * @throws Exception
091         */
092        Repository addRepository(URL repository) throws Exception;
093    
094        boolean removeRepository(URL repository);
095    
096        /**
097         * List all the repositories.
098         * 
099         * @return
100         */
101        Repository[] listRepositories();
102    
103        Resource getResource(String respositoryId);
104    }