//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//

Apache Karaf Cave can also act as a central Karaf Features gateway. For instance, you can have an unique Cave features gateway in your organization, providing
a single features repository for your Karaf instances.

Your Karaf instances on your ecosystem can connect to this unique Cave features gateway URL.

Then, you manage your features repository on the "central" Cave Features Gateway, and the Karaf instances get the features (without knowing exactly where they come from).

By default, the gateway is expose on `/cave/features-gateway-repository`. It means that, on Karaf instances, you can do:

```
karaf@root()> feature:repo-add http://host:8181/cave/features-gateway-repository
```

NB: the Karaf instances use a cache, so you have to flush the changes on the gateway using the `feature:repo-refresh` command.

==== Installation

Once Karaf Cave features repository is registered in a running Karaf instance (using `feature:repo-add cave` command for instance),
you can install the Cave Features Gateway with the `cave-features-gateway` feature:

```
karaf@root()> feature:repo-add cave
karaf@root()> feature:install cave-features-gateway
```

==== Registering features repository in the gateway

You can register several features repositories in the gateway. The main generated features repository for the gateway gathers the
registered features repositories. Thanks to that the gateway is able to "expose" features from several repositories.

===== `cave:features-gateway-register` shell command

You can simply register a features repository in the gateway using `cave:features-gateway-register` shell command. For instance,
you can register Apache Camel Karaf features repository in the gateway:

```
karaf@root()> cave:features-gateway-register mvn:org.apache.camel.karaf/apache-camel/2.24.1/xml/features
```

===== REST API

You can also use the Cave Features Gateway REST API to register a features repository on `/cave/features-gateway/api`.

The repository URL is provided as `url` header.

For instance, using `curl`, you can do:

```
curl -X POST -H "url: mvn:org.apache.camel.karaf/apache-camel/2.24.1/xml/features" http://localhost:8181/cave/features-gateway/api
```

===== JMX MBean

The `org.apache.karaf.cave:type=gateway` MBean provides the `register(String url)` operation allowing you to register a features repository in the gateway.

===== Service

The `org.apache.karaf.cave.gateway.FeaturesGatewayService` service provides the `register(String url)` method allowing you to register a features repository in the gateway.

==== List registered features repositories in the gateway

You can list the features repositories registered in the gateway.

===== `cave:features-gateway-list` shell command

The `cave:features-gateway-list` shell command gives you the registered features repositories in the gateway:

```
karaf@root()> cave:features-gateway-list
mvn:org.apache.camel.karaf/apache-camel/2.24.1/xml/features
```

===== REST API

You get list the features repositories registered on the Cave Features Gateway REST API, using `/cave/features-gateway/api` (GET). For instance using `curl`:

```
curl -X GET http://localhost:8181/cave/features-gateway/api
["mvn:org.apache.camel.karaf/apache-camel/2.24.1/xml/features"]
```

===== JMX MBean

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

===== Service

The `list()` method on the `org.apache.karaf.cave.gateway.FeaturesGatewayService` service provides the list of all registered features repositories.

==== Remove a features repository from the gateway

You can remove a features repository from the gateway.

===== `cave:features-gateway-remove` shell command

The `cave:features-gateway-remove` shell command allows you to remove a features repository from the gateway:

```
karaf@root()> cave:features-gateway-remove mvn:org.apache.camel.karaf/apache-camel/2.24.1/xml/features
```

===== REST API

You can remove a registered features repository from the gateway using the REST API on `/cave/features-gateway/api` (DELETE). The features repository URL is passed via the `url` header.
For instance, using `curl`:

```
curl -X DELETE -H "url: mvn:org.apache.camel.karaf/apache-camel/2.24.1/xml/features" http://localhost:8181/cave/features-gateway/api
```
