| package aQute.bnd.service; |
| |
| import java.io.*; |
| import java.net.*; |
| import java.util.*; |
| |
| import aQute.bnd.version.*; |
| |
| /** |
| * A Repository Plugin abstract a bnd repository. This interface allows bnd to |
| * find programs from their bsn and revisions from their bsn-version |
| * combination. It is also possible to put revisions in a repository if the |
| * repository is not read only. |
| */ |
| public interface RepositoryPlugin { |
| /** |
| * Options used to steer the put operation |
| */ |
| class PutOptions { |
| public String BUNDLE = "application/vnd.osgi.bundle"; |
| public String LIB = "application/vnd.aQute.lib"; |
| |
| /** |
| * The <b>SHA1</b> digest of the artifact to put into the repository. |
| * When specified the digest of the <b>fetched</b> artifact will be |
| * calculated and verified against this digest, <b>before</b> putting |
| * the artifact into the repository. </p> An exception is thrown if the |
| * specified digest and the calculated digest do not match. |
| */ |
| public byte[] digest = null; |
| |
| /** |
| * Specify the mime type of the importing stream. This can be either |
| * {@link #BUNDLE} or {@link #LIB}. If left open, it is up to the |
| * repository to guess the content type. |
| */ |
| public String type; |
| } |
| |
| PutOptions DEFAULTOPTIONS = new PutOptions(); |
| |
| /** |
| * Results returned by the put operation |
| */ |
| class PutResult { |
| /** |
| * A (potentially public) uri to the revision as it was put in the |
| * repository.<br/> |
| * <br/> |
| * This can be a URI to the given artifact (when it was put into the |
| * repository). This does not have to be a File URI! |
| */ |
| public URI artifact = null; |
| |
| /** |
| * The <b>SHA1</b> digest of the artifact as it was put into the |
| * repository.<br/> |
| * <br/> |
| * This can be null and it can differ from the input digest if the |
| * repository rewrote the stream for optimization reason. If the |
| */ |
| public byte[] digest = null; |
| } |
| |
| /** |
| * Put an artifact (from the InputStream) into the repository.<br/> |
| * <br/> |
| * There is NO guarantee that the artifact on the input stream has not been |
| * modified after it's been put in the repository since that is dependent on |
| * the implementation of the repository (see |
| * {@link RepositoryPlugin.PutOptions#allowArtifactChange}). |
| * |
| * @param stream |
| * The input stream with the artifact |
| * @param options |
| * The put options. See {@link RepositoryPlugin.PutOptions}, can |
| * be {@code null}, which will then take the default options like |
| * new PutOptions(). |
| * @return The result of the put, never null. See |
| * {@link RepositoryPlugin.PutResult} |
| * @throws Exception |
| * When the repository root directory doesn't exist, when the |
| * repository is read-only, when the specified checksum doesn't |
| * match the checksum of the fetched artifact (see |
| * {@link RepositoryPlugin.PutOptions#digest}), when the |
| * implementation wants to modify the artifact but isn't allowed |
| * (see {@link RepositoryPlugin.PutOptions#allowArtifactChange} |
| * ), or when another error has occurred. |
| */ |
| PutResult put(InputStream stream, PutOptions options) throws Exception; |
| |
| /** |
| * The caller can specify any number of DownloadListener objects that are |
| * called back when a download is finished (potentially before the get |
| * method has returned). |
| */ |
| |
| interface DownloadListener { |
| /** |
| * Called when the file is successfully downloaded from a remote |
| * repository. |
| * |
| * @param file |
| * The file that was downloaded |
| * @throws Exception |
| * , are logged and ignored |
| */ |
| void success(File file) throws Exception; |
| |
| /** |
| * Called when the file could not be downloaded from a remote |
| * repository. |
| * |
| * @param file |
| * The file that was intended to be downloaded. |
| * @throws Exception |
| * , are logged and ignored |
| */ |
| void failure(File file, String reason) throws Exception; |
| |
| /** |
| * Can be called back regularly before success/failure but never after. |
| * Indicates how far the download has progressed in percents. Since |
| * downloads can be restarted, it is possible that the percentage |
| * decreases. |
| * |
| * @param file |
| * The file that was intended to be downloaded |
| * @param percentage |
| * Percentage of file downloaded (can go down) |
| * @return true if the download should continue, fails if it should be |
| * canceled (and fail) |
| * @throws Exception |
| * , are logged and ignored |
| */ |
| boolean progress(File file, int percentage) throws Exception; |
| } |
| |
| /** |
| * Return a URL to a matching version of the given bundle. |
| * <p/> |
| * If download listeners are specified then the returned file is not |
| * guaranteed to exist before a download listener is notified of success or |
| * failure. The callback can happen before the method has returned. If the |
| * returned file is null then download listeners are not called back. |
| * <p/> |
| * The intention of the Download Listeners is to allow a caller to obtain |
| * references to files that do not yet exist but are to be downloaded. If |
| * the downloads were done synchronously in the call, then no overlap of |
| * downloads could take place. |
| * |
| * @param bsn |
| * Bundle-SymbolicName of the searched bundle |
| * @param version |
| * Version requested |
| * @param listeners |
| * Zero or more download listener that will be notified of the |
| * outcome. |
| * @return A file to the revision or null if not found |
| * @throws Exception |
| * when anything goes wrong, in this case no listeners will be |
| * called back. |
| */ |
| File get(String bsn, Version version, Map<String,String> properties, DownloadListener... listeners) |
| throws Exception; |
| |
| /** |
| * Answer if this repository can be used to store files. |
| * |
| * @return true if writable |
| */ |
| boolean canWrite(); |
| |
| /** |
| * Return a list of bsns that are present in the repository. |
| * |
| * @param pattern |
| * A <ahref="https://en.wikipedia.org/wiki/Glob_%28programming%29">glob pattern</a> |
| * to be matched against bsns present in the repository, or {@code null}. |
| * @return A list of bsns that match the pattern parameter or all if pattern |
| * is null; repositories that do not support browsing or querying |
| * should return an empty list. |
| * @throws Exception |
| */ |
| List<String> list(String pattern) throws Exception; |
| |
| /** |
| * Return a list of versions. |
| * |
| * @throws Exception |
| */ |
| |
| SortedSet<Version> versions(String bsn) throws Exception; |
| |
| /** |
| * @return The name of the repository |
| */ |
| String getName(); |
| |
| /** |
| * Return a location identifier of this repository |
| */ |
| |
| String getLocation(); |
| } |