asf logo

1. Overview

Apache Karaf Cave is an Apache Karaf sub-project.

Apache Karaf Cave provides three different services:

  • Artifact repositories manager

  • Karaf features gateway

  • Deployer

Each service is atomic and doesn’t depend to another one. You can only use one service or combine the services.

2. User Guide

2.1. Repositories Manager

Cave Repositories Manager is a simple but complete artifacts repository manager. You can create repositories used to store artifact. The repositories are Maven and OSGi Bundle Repository compliant. A repository doesn’t necessary store the artifacts, it can also serve as proxy or mirror to other remote repositories.

2.1.1. Installation

The first step is to register Cave features repository XML in a running Karaf instance:

karaf@root()> features:repo-add cave 4.2.0

Once it’s done, you can install the cave-repository feature:

karaf@root()> feature:install cave-repository

The Cave Repository Manager service providing:

  • shell commands to manipulate the repositories

  • MBean to manipulate the repositories via JMX

  • REST API to manipulate the repositories with REST client (like curl for instance)

2.1.2. Repositories

A Cave repository is a artifact storage that clients can use (download or uploading artifacts).

Repositories are managed by a RepositoryService and each repository has:

  • name is unique in the repository service.

  • location is where the artifacts are actually stored on the filesystem (it can be null if the repository is a proxy).

  • url is the HTTP location where the repository is accessible remotely.

  • proxy is a list of remote repositories that a repository can proxy.

  • mirror is a boolean used when the repository is a proxy. If true, when a client download an artifact from the repository, the artifact is download on remote repositories and cached on local repository storage. If false, the artifact is not cached on local repository storage.

  • realm is a JAAS security realm used to secure the users able to download/upload artifacts on the repository.

  • download role is the user role (on the realm) to secure artifacts download operation.

  • scheduling is the scheduler configuration (cron or date) to trigger an action on the repository. For instance cron:0/20 * * * * ? with execute action on the repository every 20 seconds.

  • schedulingAction is the action when scheduler is triggered. Possible actions are PURGE, DELETE, COPY targetRepositoryName and can be combined (comma separated). For instance: PURGE,DELETE.

  • upload role is the user role (on the realm) to secure artifacts upload operation.

2.1.3. Creating repository and repository details

cave:repository-create and cave:repository-info shell commands

You can simply create a repository with the cave:repository-create command:

karaf@root()> cave:repository-create myrepo

By the default, myrepo repository has the following setup:

  • myrepo location is set to ${KARAF_DATA}/cave/repository/myrepo. It can be changed at repository creation or later using cave:repository-location command (see later).

  • myrepo url is set to /cave/repository/myrepo (based on the Apache Karaf HTTP service). It can be changed at repository creation or later using cave:repository-url command (see later).

  • myrepo proxy is empty as, by default, repositories are "concrete" repository (with storage).

  • myrepo realm is karaf by default. It means that you can use roles defined in the karaf JAAS realm. You can take a look on the security and JAAS section of the Apache Karaf user guide for details.

  • myrepo downloadRole is empty, meaning that anyone can download artifacts from this repository.

  • myrepo uploadRole is empty, meaning that anyone can upload artifacts to this repository.

  • myrepo scheduling is empty, meaning no scheduler.

  • myrepo schedulingAction is empty, meaning no scheduler.

The cave:repository-create command provides the options allowing you to specify repository settings:

DESCRIPTION
        cave:repository-create

        Create a new repository

SYNTAX
        cave:repository-create [options] name

ARGUMENTS
        name
                The repository name
                (required)

OPTIONS
        -m, --mirror
                Enable repository mirror mode (for proxy)
        -sa, --scheduling-action, --action, --actions
                The repository scheduling action (DELETE, PURGE, COPY)
        --help
                Display this help message
        -dr, --download-role
                The repository security download role
        -r, --realm
                The repository security realm
                (defaults to karaf)
        -ur, --upload-role
                The repository security upload role
        -p, --proxy
                The repository proxy locations
        -l, --location
                The repository location
        -u, --url
                The repository URL
        -ps, --pool-size
                The repository pool size for the HTTP service
                (defaults to 8)
        -s, --scheduling, --schedule
                The repository scheduling (cron: or at:)

You can have details about existing repository using cave:repository-info command:

karaf@root()> cave:repository-info myrepo
Name: myrepo
Location: /opt/karaf/data/cave/repository/myrepo
URL: /cave/repository/myrepo
Proxy:
Mirror: false
Realm: karaf
Download role:
Upload role:
Scheduling:
Scheduling Actions:
Pool size: 8

You can use "regular" Apache Karaf commands related to the services used by the repository.

For instance, you can see the repository HTTP binding using http:list command:

karaf@root()> http:list
ID  │ Servlet               │ Servlet-Name               │ State       │ Alias                   │ Url
────┼───────────────────────┼────────────────────────────┼─────────────┼─────────────────────────┼─────────────────
102 │ CXFNonSpringServlet   │ cxf-osgi-transport-servlet │ Deployed    │ /cxf                    │ [/cxf/*]
116 │ MavenServlet          │ ServletModel-2             │ Deployed    │ /cave/repository/myrepo │ [/cave/repository/myrepo/*]
116 │ RepositoryRestServlet │ ServletModel-4             │ Deployed    │ /cave/repository/api    │ [/cave/repository/api/*]

NB: /cave/repository/api URL is the default REST API repository service.

It means, using your Internet browser, you can browse myrepo on http://localhost:8181/cave/repository/myrepo/.

You can also see the realm and login modules with corresponding jaas:realm-list command.

REST API

It’s also possible to create a repository using the REST API. You can find the WADL of the REST API on /cave/repository/api?_wadl URL.

For instance, you can create a repository using curl:

curl -X POST -H "Content-Type: application/json" http://localhost:8181/cave/repository/api/repositories -d '{ "name":"myrepo", "location": "", "url": "", "proxy":"", "mirror": false,"realm":"karaf","downloadRole":"","uploadRole":"","poolSize":8}'

You can also have details about a repository using the REST API. For instance, using curl:

curl -X GET http://localhost:8181/cave/repository/api/repositories/myrepo
{"name":"myrepo","location":"/opt/karaf/data/cave/repository/myrepo","url":"/cave/repository/myrepo","proxy":null,"mirror":false,"realm":"karaf","downloadRole":null,"uploadRole":null,"poolSize":8}
JMX MBean

You can also create a repository using the create(String name) or create(String name, String location, String url, String proxy, boolean mirror, String realm, String downloadRole, String uploadRole, int poolSize) operations on the org.apache.karaf.cave:type=repository MBean.

On the Repositories attribute on the org.apache.karaf.cave:type=repository MBean, you can get all details about any repository.

Service

You can also create a repository programmatically using create(String name) or create(String name, String location, String url, String proxy, boolean mirror, String realm, String downloadRole, String uploadRole, int poolSize) methods on the org.apache.karaf.cave.repository.RepositoryService.

You just have to look for the RepositoryService in the Karaf service registry. For instance using DS programming model, you can do:

@Reference
private org.apache.karaf.cave.repository.RepositoryService repositoryService;

2.1.4. Listing repositories

cave:repository-list shell command

You can list all repositories using the cave:repository-list shell command:

karaf@root()> cave:repository-list
Name   │ Location                               │ URL
───────┼────────────────────────────────────────┼────────────────────────
myrepo │ /opt/karaf/data/cave/repository/myrepo │ /cave/repository/myrepo
REST API

You can get the list of all repositories via the Cave Repository REST API using GET method on /cave/repository/api/repositories. For instance using curl:

curl -X GET http://localhost:8181/cave/repository/api/repositories
[{"name":"myrepo","location":"/home/jbonofre/Downloads/apache-karaf-4.2.7/data/cave/repository/myrepo","url":"/cave/repository/myrepo","proxy":null,"mirror":false,"realm":"karaf","downloadRole":null,"uploadRole":null,"poolSize":8}]
JMX MBean

The repositories attribute on the org.apache.karaf.cave:type=repository MBean provides a tabular data with all repositories.

Service

On the org.apache.karaf.cave.repository.RepositoryService, you can programmatically get org.apache.karaf.cave.repository.Repository collection using repositories() method.

2.1.5. Changing repository settings

You can change repository settings after it has been created using dedicated operation.

cave:repository-url, cave:repository-proxy, cave:repository-location, cave:repository-security shell commands

You can see or change the repository location using cave:repository-location command:

karaf@root()> cave:repository-location myrepo
/opt/karaf/data/cave/repository/myrepo
karaf@root()> cave:repository-location myrepo /path/to/foo
/path/to/foo

NB: The repository service will then move the repository location filesystem to the new location.

You can see or change the repository binding HTTP URL using cave:repository-url command:

karaf@root()> cave:repository-url myrepo
/cave/repository/myrepo
karaf@root()> cave:repository-url myrepo /foo
/foo

NB: The repository service will stop the repository HTTP service to start a new one on the new URL.

You can see or change the repository proxy settings using cave:repository-proxy command:

karaf@root()> cave:repository-proxy myrepo
null
karaf@root()> cave:repository-proxy -m myrepo http://repo1.maven.org/maven2@id=central
http://repo1.maven.org/maven2@id=central (mirror)

NB: When change the proxy settings, the repository location is not changed.

You can see or change the repository security settings using cave:repository-security command:

karaf@root()> cave:repository-security myrepo
Realm: karaf
Download Role: null
Upload Role: null
karaf@root()> cave:repository-security -ur admin myrepo karaf
Realm: karaf
Download Role: null
Upload Role: admin

NB: The repository service will restart the repository HTTP service with the new security settings.

REST API

You can use /cave/repository/api/repositories/myrepo URL with a updated repository json to update the repository settings. For instance using curl:

curl -X POST -H "Content-Type: application/json" http://localhost:8181/cave/repository/api/repositories/myrepo -d '{ "name":"myrepo", "location": "", "url": "", "proxy":"", "mirror": false,"realm":"karaf","downloadRole":"","uploadRole":"","poolSize":8}'
JMX MBean

You have dedicated operations on org.apache.karaf.cave:type=repository MBean to change repository settings:

  • changeLocation(String repositoryName, String newLocation) to change the location of a repository. The repository service will actually move the location filesystem.

  • changeUrl(String repositoryName, String new URL) to change the URL of a repository. The repository service will stop the previous HTTP repository service to crerate start a new one.

  • changeProxy(String repositoryName, String proxy, boolean mirror) to change the proxy settings (URLs and mirror mode). The repository location is not changed.

  • changeSecurity(String repositoryName, String realm, String downloadRole, String uploadRole) to change the security settings (realm, download, and upload roles). The repository HTTP service will be restarted with the new security settings.

Service

On the org.apache.karaf.cave.repository.RepositoryService, you have the following methods to change repository settings:

  • changeLocation(String repositoryName, String newLocation) to change the location of a repository. The repository service will actually move the location filesystem.

  • changeUrl(String repositoryName, String new URL) to change the URL of a repository. The repository service will stop the previous HTTP repository service to crerate start a new one.

  • changeProxy(String repositoryName, String proxy, boolean mirror) to change the proxy settings (URLs and mirror mode). The repository location is not changed.

  • changeSecurity(String repositoryName, String realm, String downloadRole, String uploadRole) to change the security settings (realm, download, and upload roles). The repository HTTP service will be restarted with the new security settings.

2.1.6. Upload artifacts

You can upload artifacts in a repository using a regular HTTP client (via curl for instance).

You can also directly use Maven (in your project using distributionManagement in the pom.xml) or Gradle. With Maven, you can also using deploy:deploy-file goal:

mvn deploy:deploy-file -Dfile=my.jar -Durl=http://localhost:8181/cave/repository/myrepo -DgroupId=foo -DartifactId=bar -Dversion=1.0-SNAPSHOT -Dpackaging=jar
cave:repository-artifact-add shell command

For convenience, Cave Repository provides cave:repository-artifact-add command to upload artifact in a repository:

karaf@root()> cave:repository-artifact-add myrepo mvn:commons-lang/commons-lang/2.6
REST API

You can upload an artifact using the Cave Repository REST API via /cave/repository/api/repositories/myrepo/artifact URL and providing the artifact URL as header:

curl -X POST -H "artifactUrl: mvn:commons-lang/commons-lang/2.6" http://localhost:8181/cave/repository/api/repositories/myrepo/artifact
JMX MBean

The org.apache.karaf.cave:type=repository MBean provides the addArtifact(String repositoryName, String artifactUrl) operation allowing you to add an artifact in a repository.

Service

You can programmatically add artifact in a repository using org.apache.karaf.cave.repository.RepositoryService and the addArtifact(String repositoryName, String artifactUrl) method.

2.1.7. Delete artifacts

cave:repository-artifact-delete shell command

The cave:repository-artifact-delete shell command allows you to delete an artifact from a repository:

karaf@root()> cave:repository-artifact-delete myrepo mvn:commons-lang/commons-lang/2.6
REST API

You can delete an artifact from a repository using the Cave Repository REST API via /cave/repository/api/repositories/myrepo/artifact URL and providing the artifact URL as header:

curl -X DELETE -H "artifactUrl: mvn:commons-lang/commons-lang/2.6" http://localhost:8181/cave/repository/api/repositories/myrepo/artifact
JMX MBean

The org.apache.karaf.cave:type=repository MBean provides the deleteArtifact(String repositoryName, String artifactUrl) operation allowing you to delete an artifact in a repository.

Service

You can programmatically delete artifact in a repository using org.apache.karaf.cave.repository.RepositoryService and the addArtifact(String repositoryName, String artifactUrl) method.

2.1.8. Copy repositories content

You can copy the whole content of a repository location into another repository location (it’s a full recursive copy).

cave:repository-copy shell command

The cave:repository-copy shell command copies the whole content of a source repository to a destination repository:

karaf@root()> cave:repository-copy myrepo anotherrepo
REST API

Copy is not allowed on the Cave Repository REST API.

JMX MBean

The org.apache.karaf.cave:type=repository MBean provides the copy(String sourceRepository, String destinationRepository) operation.

Service

The org.apache.karaf.cave.repository.RepositoryService service provides copy(String sourceRepository, String destinationRepository) method.

2.1.9. Proxy and mirror

A repository can proxy other repositories. The client (for instance Maven) request an artifact on the repository which "proxy" the request to other repositories define.

If the mirror mode is enabled, the artifacts are copied into the repository storage location in addition of being delivered to the client (it’s kind of artifacts caching). If the mirror mode is disabled, the repository storage is not used at all, and the artifact is passed directly.

The proxy setting define the list of remote repositories (separated with coma). In addition, you can use @id= to give a name to the remote repository (just like in the settings.xml, but this is optional but recommended), @snapshots to indicate the remote repository can contains SNAPSHOT artifacts, @noreleases to indicate the remote repository doesn’t only contains release artifacts.

For instance, you can proxy Maven Central with the following command:

karaf@root()> cave:repository-create -p http://repo1.maven.org/maven2@id=central myrepo
karaf@root()> cave:repository-info myrepo
Name: myrepo
Location: null
URL: /cave/repository/myrepo
Proxy: http://repo1.maven.org/maven2@id=central
Mirror: false
Realm: karaf
Download role:
Upload role:
Pool size: 8

Now, let’s request an artifact on myrepo repository using http://localhost:8181/cave/repository/myrepo/commons-lang/commons-lang/2.6/commons-lang-2.6.jar (remember myrepo is empty and doesn’t have any location):

curl -O http://localhost:8181/cave/repository/myrepo/commons-lang/commons-lang/2.6/commons-lang-2.6.jar
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  277k  100  277k    0     0  16.9M      0 --:--:-- --:--:-- --:--:-- 16.9M

We can see here, myrepo has correctly proxy the request to Maven Central.

Now, let’s add a location and enable mirror on myrepo repository:

karaf@root()> cave:repository-location myrepo /tmp
karaf@root()> cave:repository-proxy -m myrepo http://repo1.apache.org/maven2@id=Central
karaf@root()> cave:repository-info myrepo
Name: myrepo
Location: /tmp
URL: /cave/repository/myrepo
Proxy: http://repo1.apache.org/maven2@id=Central
Mirror: true
Realm: karaf
Download role:
Upload role:
Scheduling:
Scheduling Actions:
Pool size: 8

And now, we perform the same request using curl:

curl -O http://localhost:8181/cave/repository/myrepo/commons-lang/commons-lang/2.6/commons-lang-2.6.jar
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  277k  100  277k    0     0  16.9M      0 --:--:-- --:--:-- --:--:-- 16.9M

Now, if we check in the myrepo storage location (that we defined to /tmp), we can see the "cached" artifact:

ls -ltr /tmp/commons-lang/commons-lang/2.6/commons-lang-2.6.jar
-rw-r--r-- 1 karaf karaf 284220 oct.  13 10:56 /tmp/commons-lang/commons-lang/2.6/commons-lang-2.6.jar

2.1.10. OSGi Bundle Repository

Cave Repository supports OSGi Bundle Repository descriptor generation (aka repository.xml).

It can scan all artifacts in a repository to generate the repository.xml.

cave:repository-update-bundle-descriptor shell command

The cave:repository-update-bundle-descriptor shell command trigger the scan of all artifacts in a repository to generate a repository.xml:

karaf@root()> cave:repository-update-bundle-descriptor myrepo

We now have a repository.xml generated (or updated) in the repository storage location. Of course, it’s also available via HTTP on http://localhost:8181/cave/repository/myrepo/repository.xml.

REST API

You can trigger repository.xml update via the Cave Repository REST API on /cave/repository/api/repositories/myrepo/bundle. For instance using curl:

curl -X POST http://localhost:8181/cave/repository/api/repositories/myrepo/bundle
JMX MBean

The org.apache.karaf.cave:type=repository MBean provides the updateBundleRepositoryDescriptor(String repositoryName) operation to update the OSGi Bundle Repository repository.xml.

Service

The org.apache.karaf.cave.repository.RepositoryService service provides the updateBundleRepositoryDescriptor(String name) method to update the OSGi Bundle Repository repository.xml.

2.1.11. Purge

You can completely purge a repository store, removing all artifacts.

cave:repository-purge shell command

You can cleanup completely a repository storage location using cave:repository-purge command:

karaf@root()> cave:repository-purge myrepo

NB: you will have an error if the repository doesn’t have any storage location defined, for instance when the repository is only a proxy.

REST API

You can cleanup completely a repository storage using /cave/repository/api/repositories/myrepo/purge URL (POST). For instance, using curl:

curl X POST http://localhost:8181/cave/repository/api/repositories/myrepo/purge
JMX MBean

The org.apache.karaf.cave:type=repository MBean provides the purge(String repositoryName) operation to trigger a repository location purge.

Service

The org.apache.karaf.cave.repository.RepositoryService service provides the purge(String repositoryName) method to trigger a repository location purge.

2.1.12. Remove

You can completely remove a repository from the Cave Repository Service (by default, the repository storage is not deleted). Optionally, you can also purge the storage location.

cave:repository-remove shell command

The cave:repository-remove shell command removes a repository, optionally (using -p, --purge option) removing the repository storage:

karaf@root()> cave:repository-remove -p myrepo
REST API

You can delete a repository using /cave/repository/api/repositories/myrepo (DELETE). For instance, using curl:

curl -X DELETE http://localhost:8181/cave/repository/api/repositories/myrepo

NB: it’s not possible to purge the repository storage when removing the repository via the REST API. You have first to purge the repository location before removing the repository.

JMX MBean

The org.apache.karaf.cave;type=repository MBean provides the remove(String repositoryName, boolean purgeLocation) operation to remove a repository. If purgeLocation is true, the repository storage will be cleanup, false else.

Service

The org.apache.karaf.cave.repository.RepositoryService service provides the remove(String repositoryName, boolean purgeLocation) method to remove a repository. If purgeLocation is true, the repository storage will be cleanup, false else.

2.1.13. Repository Scheduler

You can trigger action on a repository using Cave Scheduling feature.

The repository scheduling supports cron (to periodically perform actions) or date (to execute actions at a specific time). For instance, you can perform actions every 5 seconds using cron:0/5 * * * * ? as repository scheduling. You can also execute actions at a certain date using at:2020-05-13T13:56:45.

The valid repository scheduling actions are:

  • PURGE to cleanup the repository storage location.

  • DELETE to remove the repository.

  • COPY targetRepositoryName to copy all artifacts from the repository storage to another repository.

The actions can be combined (comma separated). For instance, you can copy and purge using COPY myrepo,PURGE or purge and remove using PURGE,DELETE, etc.

The repository scheduling and actions can be defined at repository creation time (using -s and -sa options on cave:repository-create shell command for instance), or later.

cave:repository-schedule shell command

The cave:repository-schedule shell command displays or set the current repository scheduling.

For instance, you can set the scheduling using:

karaf@root()> cave:repository-schedule myrepo "cron:0/20 * * * * ?" "COPY destination"
JMX MBean

The org.apache.karaf.cave:type=repository MBean provides the changeScheduling(String name, String scheduling, String actions) operation to change the repository scheduling.

Service

The org.apache.karaf.cave.repository.RepositoryService service provides the changeScheduling(String name, String scheduling, String schedulingAction) method to change the repository scheduling.

2.2. Karaf Features Gateway

include:user-guide/features-gateway.adoc[]

2.3. Deployer

Cave Deployer allows you to manage a "farm" of Apache Karaf instances local or remote from the deployer itself.

2.3.1. Connections

To interact with a Apache Karaf instance, you have to create a connection describing the access to this instance.

A connection has:

  • an unique name for the connection

  • the JMX URL to the given Apache Karaf instance

  • the name of the Apache Karaf instance

  • username and password to connect to the Apache Karaf instance

Create connections
cave:deployer-connection-register shell command

You can add a new Apache Karaf connection using cave:deployer-connection-register shell command:

karaf@root()> cave:deployer-connection-register myconnection service:jmx:rmi:///jndi/rmi://localhost:1099/karaf-root root karaf karaf
REST API

You can create a connection via the Cave Deployer REST API on /cave/deployer/api/connections using a JSON description of your connection. For instance, using curl:

curl -X POST -H "Content-Type: application/json" http://localhost:8181/cave/deployer/api/connections -d '{
 "name": "myconnection",
 "jmxUrl": "service:jmx:rmi:///jndi/rmi://localhost:1099/karaf-root",
 "karafName": "root",
 "user": "karaf",
 "password": "karaf"
}'
JMX MBean

The org.apache.karaf.cave:type=deployer MBean provides the registerConnection(String name, String jmxUrl, String karafName, String user, String password) operation allowing you to create a new connection.

Service

The org.apache.karaf.cave.deployer.DeployerService service provides the registerConnection(Connection connection) method allowing you to create a new connection.

List connections
cave:deployer-connection-list shell command

You can list available connections using the cave:deployer-connection-list command:

karaf@root()> cave:deployer-connection-list
Name         │ JMX URL                                                 │ Instance │ Username │ Password
─────────────┼─────────────────────────────────────────────────────────┼──────────┼──────────┼─────────
myconnection │ service:jmx:rmi:///jndi/rmi://localhost:1099/karaf-root │ root     │ karaf    │ *****
REST API

You can list available connections using the Cave Deployer REST API on /cave/deployer/api/connections (GET) URL.

For instance, using curl:

curl -X GET -H "Content-Type: application/json" http://localhost:8181/cave/deployer/api/connections
[{"name":"myconnection","jmxUrl":"service:jmx:rmi:///jndi/rmi://localhost:1099/karaf-root","karafName":"root","user":"karaf","password":"karaf"}]
JMX MBean

The org.apache.karaf.cave:type=deployer MBean provides the connections attribute. It’s a tabular data where you can find all connections available.

Service

The org.apache.karaf.cave.deployer.DeployerService service provides the connections() method providing the list of all connections available.

Delete a connection
cave:deployer-connection-delete shell command

You can delete an existing connection with cave:deployer-connection-delete shell command:

karaf@root()> cave:deployer-connection-delete myconnection
REST API

You can delete an existing connection using Cave Deployer Rest API on /cave/deployer/api/connections/{name} URL (DELETE). For instance, using curl:

curl -X DELETE http://localhost:8181/cave/deployer/api/connections/myconnection
JMX MBean

The org.apache.karaf.cave:type=deployer MBean provides the deleteConnection(String name) operation to delete an existing connection.

Service

The org.apache.karaf.cave.deployer.DeployerService service provides the deleteConnection(String connectionName) method to delete an existing connection.

2.3.2. Artifacts

Download & upload artifacts

Cave Deployer is able to download an artifacts into a target directory.

For instance you can download an artifact using cave:deployer-download shell command:

karaf@root()> cave:deployer-download mvn:commons-lang/commons-lang/2.6 /path/to/my/repo

You can also use Cave Deployer REST API on /cave/deployer/api/download (POST). The artifact URL is passed using artifact header and the directory is passed using directory header.

For instance, using curl:

curl -X POST -H "artifact: mvn:commons-lang/commons-lang/2.6" -H "directory: /path/to/my/repo" http://localhost:8181/cave/deployer/api/download

You can also use the download(String url, String directory) operation on the org.apache.karaf.cave:type=deployer MBean.

On the org.apache.karaf.cave.deployer.DeployerService service, you can also use the download(String artifact, String directory) method.

On the other hand, you can also upload an artifact to a target repository providing the Maven coordinates. It’s exactly the same as doing mvn deploy:deploy-file.

To upload an artifact, you can use the cave:deployer-upload shell command:

karaf@root()> cave:deployer-upload -g groupId -a artifactId -v 1.0-SNAPSHOT mvn:foo/bar/x.x http://host/repository

You can also use the Cave Deployer REST API on /cave/deployer/api/upload (POST) with the following header parameters:

  • groupId

  • artifactId

  • version

  • artifactUrl

  • repositoryUrl

For instance, using curl:

curl -X POST -H "groupId: groupId" -H "artifactId: artifactId" -H "version: 1.0-SNAPSHOT" -H "artifactUrl: mvn:foo/bar/x.x" -H "repositoryUrl: http://host/repository" http://localhost:8181/cave/deployer/api/upload

You can also use the upload(String groupId, String artifactId, String version, String artifactUrl, String repositoryUrl) operation on the org.apache.karaf.cave:type=deployer MBean.

The org.apache.karaf.cave.deployer.DeployerService service also provides the upload(String groupId, String artifactId, String version, String artifactUrl, String repositoryUrl) method.

Extract & explode artifacts

Cave Deployer is also able to process zip and kar artifacts.

Cave Deployer is able to extract zip or kar files to a given Maven repository or local directory:

  • explode will download and extract an artifact into a target folder/repository, looking for features repositories XML (typically in KAR files)

  • extract will download and extract an artifact into a target folder/repository

To explode an artifact into a target Maven repository, you can use cave:deployer-explode shell command:

karaf@root()> cave:deployer-explode mvn:foo/bar/1.0/kar /path/to/repository

You can also use the Cave Deployer REST API on /cave/deployer/api/explode URL (POST) with url header for the artifact URL, and repository header for the repository URL. For instance, using curl:

curl -X POST -H "url: mvn:foo/bar/1.0/kar" -H "repository: /path/to/repository" http://localhost:8181/cave/deployer/api/explode
["foo.xml"]

You can also use explode(String url, String repository) operation on the org.apache.karaf.cave:type=deployer MBean.

The org.apache.karaf.cave.deployer.DeployerService also provides the explode(String url, String repository) method.

Similar to explode, you can extract artifact (without looking for features repositories XML).

You can use the cave:deployer-extract shell command to extract an artifact:

karaf@root()> cave:deployer-extract mvn:foo/bar/1.0/zip /path/to/directory

You can also use the Cave Deployer REST API on /cave/deployer/api/extract URL (POST) with url header for the artifact URL, and directory header for the directory. For instance, using curl:

curl -X POST -H "url: mvn:foo/bar/1.0/zip" -H "directory: /path/to/directory" http://localhost:8181/cave/deployer/api/extract

The org.apache.karaf.cave:type=deployer MBean also provides extract(String url, String directory) operation to extract an artifact into a directory.

You can also programmatically use ` extract(String url, String directory)` method on the org.apache.karaf.cave.deployer.DeployerService service.

2.3.3. Features

Assemble features

You can create new Karaf features by composing existing features, configurations or bundles.

For instance, you can create myfeature composed by feature1, feature2, bundle1, bundle2.

  • karaf@root()> cave:deployer-assemble-feature -g groupId -a artifactId -v 1.0-SNAPSHOT myfeature http://myrepo feature1 feature2

  • Using assembleFeature(String groupId, String artifactId, String version, String repositoryUrl, String feature, List<String> repositories, List<String> features, List<String> bundles) operation on the org.apache.karaf.cave:type=deployer MBean

  • Using assembleFeature(String groupId, String artifactId, String version, String repositoryUrl, String feature, List<String> featureRepositoryUrls, List<String> features, List<String> bundles, List<Config> configs) method on the org.apache.karaf.cave.deployer.DeployerService service

Add features repositories

  • karaf@root()> cave:deployer-feature-repo-add myconnection mvn:foo/bar/1.0/xml/features

  • curl -X POST -H "artifactUrl: mvn:foo/bar/1.0/xml/features" http://localhost:8181/cave/deployer/api/connections/myconnection/features/repositories

  • addFeatureRepository(String url, String connection) operation on the org.apache.karaf.cave:type=deployer MBean.

  • addFeaturesRepository(String featuresRepositoryUrl, String connection) method on the org.apache.karaf.cave.deployer.DeployerService service.

List features repositories

  • karaf@root()> cave:deployer-feature-repo-list myconnection

  • curl -X GET http://localhost:8181/cave/deployer/api/connections/myconnection/features/repositories

  • getFeatureRepositories(String connection) operation on the org.apache.karaf.cave:type=deployer MBean.

  • featuresRepositories(String connection) method on the org.apache.karaf.cave.deployer.DeployerService service.

List features provided by a features repository

  • karaf@root()> cave:deployer-feature-repo-provide mvn:foo/bar/1.0/xml/features

  • curl -X GET -H "featuresRepositoryUrl: mvn:foo/bar/1.0/xml/features" http://localhost:8181/cave/deployer/api/features/repository

  • getProvidedFeatures(String featuresRepositoryUrl) operation on the org.apache.karaf.cave:type=deployer MBean.

  • providedFeatures(String featuresRepositoryUrl) method on the org.apache.karaf.cave.deployer.DeployerService service.

Remove features repositories

  • karaf@root()> cave:deployer-feature-repo-remove myconnection mvn:foo/bar/1.0/xml/features

  • curl -X DELETE -H "artifactUrl: mvn:foo/bar/1.0/xml/features" http://localhost:8181/cave/deployer/api/connections/myconnection/features/repositories

  • removeFeatureRepository(String repository, String connection) operation on the org.apache.karaf.cave:type=deployer MBean.

  • removeFeaturesRepository(String featuresRepositoryUrl, String connection) method on the org.apache.karaf.cave.deployer.DeployerService service.

Install features

  • karaf@root()> cave:deployer-feature-install myconnection myfeature

  • curl -X POST http://localhost:8181/cave/deployer/api/connections/myconnection/features/myfeature

  • installFeature(String feature, String connection) operation on the org.apache.karaf.cave:type=deployer MBean.

  • installFeature(String feature, String connection) method on the org.apache.karaf.cave.deployer.DeployerService service.

List features

  • karaf@root()> cave:deployer-feature-list myconnection

  • curl -X GET http://localhost:8181/cave/deployer/api/connections/myconnection/features

  • getFeatures(String connection) operation on the org.apache.karaf.cave:type=deployer MBean.

  • features(String connection) method on the org.apache.karaf.cave.deployer.DeployerService service.

List installed features

  • karaf@root()> cave:deployer-feature-installed-list myconnection

  • installedFeatures(String connection) method on the org.apache.karaf.cave.deployer.DeployerService service.

Uninstall features

  • karaf@root()> cave:deployer-feature-uninstall myconnection myfeature

  • curl -X DELETE http://localhost:8181/cave/deployer/api/connections/myconnection/features/myfeature

  • uninstallFeature(String feature, String connection) operation on the org.apache.karaf.cave:type=deployer MBean.

  • uninstallFeature(String feature, String connection) method on the org.apache.karaf.cave.deployer.DeployerService service.

2.3.4. KARs

Install KAR

  • karaf@root()> cave:deployer-kar-install myconnection mvn:foo/bar/1.0/kar

  • curl -X POST -H "artifactUrl: mvn:foo/bar/1.0/kar" http://localhost:8181/cave/deployer/api/connections/myconnection/kars

  • installKar(String url, String connection) operation on the org.apache.karaf.cave:typye=deployer MBean.

  • installKar(String karUrl, String connection) on the org.apache.karaf.cave.deployer.DeployerService service.

List KARs

  • karaf@root()> cave:deployer-kar-list myconnection

  • curl -X GET http://localhost:8181/cave/deployer/api/connections/myconnection/kars

  • getKars(String connection) operation on the org.apache.karaf.cave:type=deployer MBean.

  • kars(String connection) method on the org.apache.karaf.cave.deployer.DeployerService service.

Uninstall KAR

  • karaf@root()> cave:deployer-kar-uninstall myconnection mykar

  • curl -X DELETE http://localhost:8181/cave/deployer/api/connections/myconnection/kars/mykar

  • uninstallKar(String id, String connection) operation on the org.apache.karaf.cave:type=deployer MBean.

  • uninstallKar(String id, String connection) method on the org.apache.karaf.cave.deployer.DeployerService service.

2.3.5. Bundles

Install bundle

  • karaf@root()> cave:deployer-bundle-install myconnection mvn:foo/bar/1.0

  • curl -X POST -H "artifactUrl: mvn:foo/bar/1.0" http://localhost:8181/cave/deployer/api/connections/myconnection/bundles

  • installBundle(String url, String connection) operation on the org.apache.karaf.cave:type=deployer MBean.

  • installBundle(String artifactUrl, String connection) method on the org.apache.karaf.cave.deployer.DeployerService service.

List bundles

  • karaf@root()> cave:deployer-bundle-list myconnection

  • curl -X GET http://localhost:8181/cave/deployer/api/connections/myconnection/bundles

  • getBundles(String connection) operation on the org.apache.karaf.cave:type=deployer MBean.

  • bundles(String connection) method on the org.apache.karaf.cave.deployer.DeployerService service.

Start bundle

  • karaf@root()> cave:deployer-bundle-start myconnection 81

  • curl -X POST http://localhost:8181/cave/deployer/api/connections/myconnection/bundles/81/start

  • startBundle(String id, String connection) operation on the org.apache.karaf.cave:type=deployer MBean.

  • startBundle(String id, String connection) method on the org.apache.karaf.cave.deployer.DeployerService service.

Stop bundle

  • karaf@root()> cave:deployer-bundle-stop myconnection 81

  • curl -X POST http://localhost:8181/cave/deployer/api/connections/myconnection/bundles/81/stop

  • stopBundle(String id, String connection) operation on the org.apache.karaf.cave:type=deployer MBean.

  • stopBundle(String id, String connection) method on the org.apache.karaf.cave.deployer.DeployerService service.

Uninstall bundle

  • karaf@root()> cave:deployer-bundle-uninstall myconnection 81

  • curl -X DELETE http://localhost:8181/cave/deployer/api/connections/myconnection/bundles/81

  • uninstallBundle(String id, String connection) operation on the org.apache.karaf.cave:type=deployer MBean.

  • uninstallBundle(String id, String connection) method on the org.apache.karaf.cave.deployer.DeployerService service.

2.3.6. Configurations

Create configuration

  • karaf@root()> cave:deployer-config-create myconnection myconfig

  • curl -X POST http://localhost:8181/cave/deployer/api/connections/myconnection/configurations/myconfig

  • createConfig(String pid, String connection) operation on the org.apache.karaf.cave:type=deployer MBean.

  • createConfig(String pid, String connection) method on the org.apache.karaf.cave.deployer.DeployerService service.

Create configuration factory

  • karaf@root()> cave:deployer-config-factory-create myconnection myfactory alias

  • curl -X POST http://localhost:8181/cave/deployer/api/connections/myconnection/configurations/factories/myfactory

  • createConfigFactory(String factoryPid, String alias, String connection) operation on the org.apache.karaf.cave:type=deployer MBean.

  • createConfigurationFactory(String factoryPid, String alias, String connection) method on the org.apache.karaf.cave.deployer.DeployerService service.

List configurations

  • karaf@root()> cave:deployer-config-list myconnection

  • curl -X GET http://localhost:8181/cave/deployer/api/connections/myconnection/configurations

  • configs(String connection) operation on the org.apache.karaf.cave:type=deployer MBean.

  • configs(String connection) method on the org.apache.karaf.cave.deployer.DeployerService service.

Set configuration property

  • karaf@root()> cave:deployer-config-property-set myconnection myconfiguration myproperty myvalue

  • setConfigProperty(String pid, String key, String value, String connection) operation on the org.apache.karaf.cave:type=deployer MBean.

  • setConfigProperty(String pid, String key, String value, String connection) method on the org.apache.karaf.cave.deployer.DeployerService service.

List configuration properties

  • karaf@root()> cave:deployer-config-property-list myconnection myconfiguration

  • curl -X GET http://localhost:8181/cave/deployer/api/connections/myconnection/configurations/myconfiguration/properties

  • getConfigProperties(String pid, String connection) operation on the org.apache.karaf.cave:type=deployer MBean.

  • configProperties(String pid, String connection) method on the org.apache.karaf.cave.deployer.DeployerService service.

Delete configuration property

  • karaf@root()> cave:deployer-config-property-delete myconnection myconfiguration myproperty

  • deleteConfigProperty(String pid, String key, String connection) operation on the org.apache.karaf.cave:type=deployer MBean.

  • deleteConfigProperty(String pid, String key, String connection) methood on the org.apache.karaf.cave.deployer.DeployerService service.

Delete configuration

  • karaf@root()> cave:deployer-config-delete myconnection myconfiguration

  • curl -X DELETE http://localhost:8181/cave/deployer/api/connections/myconnection/configurations/myconfiguration

  • deleteConfig(String pid, String connection) operation on the org.apache.karaf.cave:type=deployer MBean.

  • deleteConfig(String pid, String connection) method on the org.apache.karaf.cave.deployer.DeployerService service.

2.3.7. Karaf Cellar cluster

Cave Deployer is able to administrate a Karaf Cellar cluster.

List cluster nodes

  • cave:deployer-cluster-node-list myconnection

  • curl -X GET http://localhost:8181/cave/deployer/api/cluster/nodes

  • getClusterNodes(String connection) operation on the org.apache.karaf.cave:type=deployer MBean.

  • clusterNodes(String connection) method on the org.apache.karaf.cave.deployer.DeployerService service.

List cluster groups

  • cave:deployer-cluster-group-list myconnection

  • curl -X GET http://localhost:8181/cave/deployer/api/cluster/groups

  • getClusterGroups(String connection) operation on the org.apache.karaf.cave:type=deployer MBean.

  • clusterGroups(String connection) method on the org.apache.karaf.cave.deployer.DeployerService service.

Add features repository to cluster group

  • cave:deployer-cluster-feature-repo-add myconnection myclustergroup mvn:foo/bar/1.0/xml/features

  • curl -X POST -H "url: mvn:foo/bar/1.0/xml/features" http://localhost:8181/cave/deployer/api/connections/myconnection/cluster/groups/myclustergroup/features/repositories

  • clusterFeatureRepositoryAdd(String url, String clusterGroup, String connection) operation on the org.apache.karaf.cave:type=deployer MBean.

  • clusterAddFeaturesRepository(String url, String clusterGroup, String connection) method on the org.apache.karaf.cave.deployer.DeployerService service.

Remove features repository from cluster group

  • cave:cluster-feature-repo-remove myconnection myclustergroup mvn:foo/bar/1.0/xml/features

  • curl -X DELETE -H "url: mvn:foo/bar/1.0/xml/features" http://localhost:8181/cave/deployer/api/connections/myconnection/cluster/groups/myclustergroup/features/repositories

  • clusterFeatureRepositoryRemove(String url, String clusterGroup, String connection) operation on the org.apache.karaf.cave:type=deployer MBean.

  • clusterRemoveFeaturesRepository(String url, String clusterGroup, String Connection) method on the org.apache.karaf.cave.deployer.DeployerService service.

Install feature on cluster group

  • cave:deployer-cluster-feature-install myconnection mygroup myfeature

  • curl -X POST http://localhost:8181/cave/deployer/api/connections/myconnection/cluster/groups/mygroup/features/myfeature

  • clusterFeatureInstall(String feature, String clusterGroup, String connection) operation on the org.apache.karaf.cave:type=deployer MBean.

  • clusterFeatureInstall(String feature, String clusterGroup, String connection) method on the org.apache.karaf.cave.deployer.DeployerService service.

Uninstall feature from cluster group

  • cave:deployer-cluster-feature-uninstall myconnection mygroup myfeature

  • curl -X DELETE http://localhost:8181/cave/deployer/api/connections/myconnection/cluster/groups/mygroup/features/myfeature

  • clusterFeatureUninstall(String feature, String clusterGroup, String connection) operation on the org.apache.karaf.cave:type=deployer MBean.

  • clusterFeatureUninstall(String feature, String clusterGroup, String connection) method on the org.apache.karaf.cave.deployer.DeployerService service.