aQute.bnd.service.RepositoryPlugin Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of biz.aQute.bndlib Show documentation
Show all versions of biz.aQute.bndlib Show documentation
bndlib: A Swiss Army Knife for OSGi
package aQute.bnd.service;
import java.io.File;
import java.io.InputStream;
import java.net.URI;
import java.util.List;
import java.util.Map;
import java.util.SortedSet;
import aQute.bnd.osgi.Processor;
import aQute.bnd.version.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 static final String BUNDLE = "application/vnd.osgi.bundle";
public static final String LIB = "application/vnd.aQute.lib";
/**
* The SHA1 digest of the artifact to put into the repository.
* When specified the digest of the fetched artifact will be
* calculated and verified against this digest, before putting
* the artifact into the repository.
*
* 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;
/**
* When set, the repository must use it as the bsn
*/
public String bsn = null;
/**
* When set, the repository must use it as the version
*/
public Version version = null;
/**
* Provides the context. This is an optional parameter but if possible
* should link to the closest context of the dumped artifact. It will be
* used for reporting and getting properties/instructions.
*/
public Processor context;
}
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.
*
* 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 SHA1 digest of the artifact as it was put into the
* repository.
*
* 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;
/**
* Set to true if this artifact was already released
*/
public boolean alreadyReleased;
}
/**
* Put an artifact (from the InputStream) into the repository.
*
* 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.
*
* @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, 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.
*
* 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.
*
* 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 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
*
* glob pattern 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 list(String pattern) throws Exception;
/**
* Return a list of versions.
*
* @throws Exception
*/
SortedSet versions(String bsn) throws Exception;
/**
* @return The name of the repository
*/
String getName();
/**
* Return a location identifier of this repository
*/
String getLocation();
}