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 }