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.  
022package org.osgi.service.obr;
023
024import 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 */
046public 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}