You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@karaf.apache.org by jb...@apache.org on 2014/01/11 16:45:34 UTC
[3/3] git commit: Update Cave documentation
Update Cave documentation
Project: http://git-wip-us.apache.org/repos/asf/karaf-cave/repo
Commit: http://git-wip-us.apache.org/repos/asf/karaf-cave/commit/1c360c70
Tree: http://git-wip-us.apache.org/repos/asf/karaf-cave/tree/1c360c70
Diff: http://git-wip-us.apache.org/repos/asf/karaf-cave/diff/1c360c70
Branch: refs/heads/master
Commit: 1c360c70b8a2502bb811155e2cfc0e11300054ba
Parents: a6d844f
Author: Jean-Baptiste Onofré <jb...@apache.org>
Authored: Sat Jan 11 16:45:03 2014 +0100
Committer: Jean-Baptiste Onofré <jb...@apache.org>
Committed: Sat Jan 11 16:45:03 2014 +0100
----------------------------------------------------------------------
.../src/main/webapp/developer-guide/index.conf | 5 -
manual/src/main/webapp/index.conf | 5 +-
manual/src/main/webapp/manual.conf | 9 +-
manual/src/main/webapp/overview.conf | 2 +-
.../webapp/user-guide/administrate-cave.conf | 22 ++-
.../src/main/webapp/user-guide/cave-client.conf | 7 -
.../main/webapp/user-guide/cave-repository.conf | 162 ++++++++++++-------
.../main/webapp/user-guide/http-wrapper.conf | 47 +++---
manual/src/main/webapp/user-guide/index.conf | 16 +-
.../main/webapp/user-guide/installation.conf | 34 ++--
.../main/webapp/user-guide/obr-commands.conf | 14 +-
.../webapp/user-guide/populate-repository.conf | 45 +++---
.../webapp/user-guide/proxy-repository.conf | 20 +--
.../main/webapp/user-guide/rest-service.conf | 7 -
14 files changed, 216 insertions(+), 179 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/karaf-cave/blob/1c360c70/manual/src/main/webapp/developer-guide/index.conf
----------------------------------------------------------------------
diff --git a/manual/src/main/webapp/developer-guide/index.conf b/manual/src/main/webapp/developer-guide/index.conf
deleted file mode 100644
index 417946e..0000000
--- a/manual/src/main/webapp/developer-guide/index.conf
+++ /dev/null
@@ -1,5 +0,0 @@
-h1. Apache Karaf Cave Developer Guide
-
-* [Building Karaf Cave|/developer-guide/building]
-* [Implementing backend|/developer-guide/backend]
-* [REST client|/developer-guide/rest]
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/karaf-cave/blob/1c360c70/manual/src/main/webapp/index.conf
----------------------------------------------------------------------
diff --git a/manual/src/main/webapp/index.conf b/manual/src/main/webapp/index.conf
index fe6de8f..80a0d2d 100644
--- a/manual/src/main/webapp/index.conf
+++ b/manual/src/main/webapp/index.conf
@@ -2,6 +2,5 @@ h1. Apache Karaf Cave
This project contains documentation about Apache Karaf Cave.
-* [Karaf Cave Overview|overview]
-* [User Guide|user-guide/index]
-* [Developer Guide|developer-guide/index]
\ No newline at end of file
+* [Overview|overview]
+* [User Guide|user-guide/index]
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/karaf-cave/blob/1c360c70/manual/src/main/webapp/manual.conf
----------------------------------------------------------------------
diff --git a/manual/src/main/webapp/manual.conf b/manual/src/main/webapp/manual.conf
index 4bfbee6..656bc29 100644
--- a/manual/src/main/webapp/manual.conf
+++ b/manual/src/main/webapp/manual.conf
@@ -29,5 +29,10 @@ h1. Overview
{include:overview.conf}
h1. User Guide
-
-h1. Developer Guide
+{include:/user-guide/installation}
+{include:/user-guide/cave-repository}
+{include:/user-guide/populate-repository}
+{include:/user-guide/proxy-repository}
+{include:/user-guide/obr-commands}
+{include:/user-guide/http-wrapper}
+{include:/user-guide/administrate-cave}
http://git-wip-us.apache.org/repos/asf/karaf-cave/blob/1c360c70/manual/src/main/webapp/overview.conf
----------------------------------------------------------------------
diff --git a/manual/src/main/webapp/overview.conf b/manual/src/main/webapp/overview.conf
index 4242d1e..25a8832 100644
--- a/manual/src/main/webapp/overview.conf
+++ b/manual/src/main/webapp/overview.conf
@@ -26,4 +26,4 @@ remote http:), looking for OSGi bundles, and copy the artifacts in the Cave repo
Karaf Cave provides two components:
* the cave-server is the OBR and KFR server, including the storage, the management layer, the REST service layer, etc.
-* the cave-client is a local OBR service proxy that use a remote Cave OBR server.
\ No newline at end of file
+* the cave-client is a local OBR service proxy that use a remote Cave OBR server (not yet available).
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/karaf-cave/blob/1c360c70/manual/src/main/webapp/user-guide/administrate-cave.conf
----------------------------------------------------------------------
diff --git a/manual/src/main/webapp/user-guide/administrate-cave.conf b/manual/src/main/webapp/user-guide/administrate-cave.conf
index 89126e2..6c3b30b 100644
--- a/manual/src/main/webapp/user-guide/administrate-cave.conf
+++ b/manual/src/main/webapp/user-guide/administrate-cave.conf
@@ -1,9 +1,21 @@
-h1. Administrate Cave Server
+h1. Administration
-When you install the Cave Server, it binds a set of JMX MBeans.
+When you install Apache Karaf Cave server, it provides a new CaveServerMBean.
-These MBeans allow you to monitore and administrate the Cave Server.
+This MBean use the following object name:
-It means that you can manipulate Cave Repositories using a JMX client.
+{code}
+org.apache.karaf.cave:type=repository,name=*
+{code}
-TODO: complete with the MBeans detail.
\ No newline at end of file
+Thanks to this MBean, using any JMX client (like jconsole for instance), you can do all actions as you can using the
+{{cave:*}} commands:
+
+* void createRepository(String name, String location, boolean generateObr, boolean install) throws Exception;
+* void destroyRepository(String name) throws Exception;
+* void installRepository(String name) throws Exception;
+* void uninstallRepository(String name) throws Exception;
+* void populateRepository(String name, String url, boolean generateObr, String filter) throws Exception;
+* void proxyRepository(String name, String url, boolean generateObr, String filter) throws Exception;
+* void updateRepository(String name) throws Exception;
+* void uploadArtifact(String repository, String artifactUrl, boolean generateObr) throws Exception;
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/karaf-cave/blob/1c360c70/manual/src/main/webapp/user-guide/cave-client.conf
----------------------------------------------------------------------
diff --git a/manual/src/main/webapp/user-guide/cave-client.conf b/manual/src/main/webapp/user-guide/cave-client.conf
deleted file mode 100644
index 7b29ec2..0000000
--- a/manual/src/main/webapp/user-guide/cave-client.conf
+++ /dev/null
@@ -1,7 +0,0 @@
-h1. Cave Client
-
-The Cave Client is an implementation of the OBR RepositoryAdmin OSGi service which proxy all calls to a Cave Server.
-
-For the Karaf instance, the OBR service looks local, but in fact, each method call is forwarded to the Cave Server.
-
-TODO: complete when the Cave Client will be fully implemented.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/karaf-cave/blob/1c360c70/manual/src/main/webapp/user-guide/cave-repository.conf
----------------------------------------------------------------------
diff --git a/manual/src/main/webapp/user-guide/cave-repository.conf b/manual/src/main/webapp/user-guide/cave-repository.conf
index 9f6a526..660a1ac 100644
--- a/manual/src/main/webapp/user-guide/cave-repository.conf
+++ b/manual/src/main/webapp/user-guide/cave-repository.conf
@@ -1,109 +1,159 @@
-h1. Cave Repository
-
-A Karaf Cave Repository is a container for:
+h1. Repository
+
+A Cave Repository is a container for:
+
+* OSGi bundles (jar files)
+* OBR (OSGi Bundle Repository) metadata (aka a repository.xml file)
+
+By default, a repository uses a filesystem backend for the storage, the directory used is KARAF_BASE/cave.
+
+You can change the storage location in the {{etc/org.apache.karaf.cave.server.storage.cfg}} configuration file:
+
+{code}
+################################################################################
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You 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.
+#
+################################################################################
+
+#
+# Storage location where Apache Karaf Cave create repositories by default
+#
+storage.location=cave
+{code}
-* the OSGi bundles (jar files)
-* the OBR metadata (repository.xml)
+For instance, you can define {{/var/cave/store}} for the {{storage.location}} property.
-By default, a Cave Repository uses a filesystem backend for the storage, the directory used is KARAF_BASE/case.
+h2. Create
-You can change the storage location in the etc/org.apache.karaf.cave.server.storage.cfg configuration file:
+The {{cave:repository-create}} command creates a new repository:
{code}
-# default value
-storage.location=cave
-# custom storage location
-#storage.location=/path/to/your/storage/folder
+karaf@root> cave:repository-create my-repository
{code}
-h2. Create a Cave Repository
+A repository is identified by a name, {{my-repository}} in our example.
+
+Apache Karaf Cave creates the repository storage for you.
-The cave:repository-create command creates a Cave Repository:
+If you want to use an existing directory, and avoid Cave to create one in the storage location, you can use the {{-l}}
+({{--location}}) option:
{code}
-karaf@root> cave:repository-create cave-repo
+karaf@root> cave:repository-create -l /home/user/.m2/repository m2
{code}
-A Cave Repository is identified by a name, cave-repo in our example.
-
-Karaf Cave will create the repository storage. In this example, you can see a cave-repo folder in the storage location:
+By default, Apache Karaf Cave scans the repository storage and create the OBR metadata. You can use the {{-no}} ({{--no-obr-generate}})
+option to avoid this step:
{code}
-shell$ ls cave/
-cave-repo
+karaf@root> cave:repository-create -no -l /home/user/.m2/repository m2
{code}
-If you want to use an existing directory, and avoid Cave to create one in the storage location, you can use the -l or
---location option:
+By default, Apache Karaf Cave registers (installs) a new repository into the OBR service. You can use the {{-ni}} ({{--no-install}})
+option to avoid this step:
{code}
-karaf@root> cave:repository-create -l /home/jbonofre/.m2/repository m2
+karaf@root> cave:repository-create -ni -l /home/user/m2/repository m2
{code}
-You can also generate the OBR metadata at creation time using the -s or --scan option. Karaf Cave scans the repository
-storage, looking for OSGi bundles, and create the OBR metadata:
+NB: the {{-no}} and {{-ni}} options are interesting when you use an existing location for the repository. If you create a
+new empty repository, these options don't have really any effect.
+
+h2. List
+
+You can list the repositories:
{code}
-karaf@root> cave:repository-create -s -l /home/jbonofre/.m2/repository m2
+karaf@root> cave:repositories-list
+Name Location
+[my-repository] [/opt/apache-karaf-2.3.3/cave/my-repository]
+[m2] [/home/user/.m2/repository]
{code}
-In the same way, you can register the Cave Repository in the OBR service directly at creation time. For instance, you
-can combine the three options to:
+You can find the repository name and location.
+
+h2. Repository and OBR service
+
+By default, Apache Karaf Cave installs the repository in the Apache Karaf OBR service.
-1. create the Cave Repository using an existing location
-2. scan for OSGi bundle and create the OBR metadata
-3. register the Cave repository in the OBR service
+You can see the installed repositories using the {{obr:listurl}} command:
{code}
-karaf@root> cave:repository-create -s -r -l /home/jbonofre/.m2/repository m2
+karaf@root> obr:listurl
+file:/home/jbonofre/.m2/repository/repository.xml
+file:/home/jbonofre/apache-karaf-2.3.3/cave/my-repository/repository.xml
{code}
-h2. List of Cave Repositories
-
-You can list the Cave Repositories:
+You can refresh a repository or install a repository in the OBR service using the {{cave:repository-install}} command:
{code}
-karaf@root> cave:repositories-list
-Name Location
-[cave-repo] [/home/jbonofre/apache-karaf-2.3.1/cave/cave-repo]
-[m2] [/home/jbonofre/.m2/repository]
+karaf@root> cave:repository-install my-repository
{code}
-h2. Remove and destroy a Cave Repository
-
-You can remove a Cave Repository from the repositories registry:
+You can uninstall a repository from the Apache Karaf OBR service using the {{cave:repository-uninstall}} command:
{code}
-karaf@root> cave:repository-uninstall cave-repo
+karaf@root> cave:repository-uninstall my-repository
{code}
-The Cave Repository storage won't be removed. It means that the artifacts will stay in the storage folder.
-
-If you want to destroy a Cave Repository, including the artifacts and the storage folder, you have to use:
+You can see with the {{obr:listurl}} command that the repository is no more known by the OBR service:
{code}
-karaf@root> cave:repository-destroy cave-repo
+karaf@root> obr:listurl
+file:/home/jbonofre/.m2/repository/repository.xml
{code}
-h2. Generate OBR metadata
+You can "re-install" the repository at any time using the {{cave:repository-install}} command again:
-You can generate the OBR metadata:
+{code}
+karaf@root> cave:repository-install my-repository
+karaf@root> obr:listurl
+file:/home/jbonofre/.m2/repository/repository.xml
+file:/home/jbonofre/apache-karaf-2.3.3/cave/my-repository/repository.xml
+{code}
+
+At any time, you can force the generation and update of the OBR metadata using the {{cave:repository-update}} command:
{code}
-karaf@root> cave:repository-scan cave-repo
+karaf@root> cave:repository-update my-repository
{code}
-Cave will scan the Cave Repository storage, looking for OSGi bundle, and generate the OBR metadata.
+This command scan the repository storage location, seeking all OSGi bundles, and generate the OBR metadata (aka a repository.xml).
+
+NB: If you add or remove any artifact in the repository storage location by hand (for instance, using cp, rm, etc on Unix),
+you have to update the repository OBR metadata using the {{cave:repository-update}} command.
-h2. Register Cave Repository in the OBR service
+h2. Destroy
-Once you have generated the OBR metadata, you can register the Cave Repository in the OBR service:
+The {{cave:repository-destroy}} command deletes the repository storage location:
{code}
-karaf@root> cave:repository-install cave-repo
+karaf@root> cave:repository-destroy my-repository
{code}
-You are now ready to use the [OBR commands|/user-guide/obr-command].
+{warning}
+Be aware that this command completely deletes the repository storage. By extremely careful when using this command
+with repository using "custom" location.
+{warning}
+
+h2. What's next
+
+Apache Karaf Cave provides a HTTP service to expose the repositories. It allows you to use the repositories remotely.
+You can find details in the [HTTP wrapper service section|http-wrapper] of the user guide.
-You can also use a remote Cave server via the [HTTP Wrapper Service|/user-guide/http-wrapper]
-or the [Cave Client|/user-guide/client].
\ No newline at end of file
+If repositories are installed in the OBR service, you can use the OBR command as explained in the [OBR commands section|obr-command]
+of the user guide.
http://git-wip-us.apache.org/repos/asf/karaf-cave/blob/1c360c70/manual/src/main/webapp/user-guide/http-wrapper.conf
----------------------------------------------------------------------
diff --git a/manual/src/main/webapp/user-guide/http-wrapper.conf b/manual/src/main/webapp/user-guide/http-wrapper.conf
index 301cb98..f4c83ec 100644
--- a/manual/src/main/webapp/user-guide/http-wrapper.conf
+++ b/manual/src/main/webapp/user-guide/http-wrapper.conf
@@ -1,18 +1,18 @@
-h1. HTTP Wrapper Service
+h1. HTTP wrapper service
-When you install the Cave Server, it starts a HTTP service wrapper.
+When you install the Apache Karaf Cave Server, it starts a HTTP service wrapper.
-It means that all artifacts and OBR metadata presents locally are exposed in HTTP.
+It means that all artifacts and OBR metadata presents in local repositories are exposed over HTTP.
h2. OBR metadata access
-Assuming that you have the following Cave Repositories:
+Assuming that you have the following repositories:
{code}
karaf@root> cave:repositories-list
Name Location
-[cave-repo] [/home/jbonofre/apache-karaf-2.2.2/cave/cave-repo]
-[m2] [/home/jbonofre/.m2/repository]
+[cave-repo] [/opt/apache-karaf-2.2.2/cave/my-repository]
+[m2] [/home/user/.m2/repository]
{code}
You can access the OBR metadata using the following URL in your favorite browser:
@@ -24,34 +24,37 @@ http://localhost:8181/cave/m2-repository.xml
and
{code}
-http://localhost:8181/cave/cave-repo-repository.xml
+http://localhost:8181/cave/my-repository-repository.xml
{code}
-NB: the port 8181 is the default one of the Karaf HTTP service.
+NB: the port 8181 is the default one of the Apache Karaf HTTP service.
-To access the OBR metadata, the URL format is:
+You can see that the URL follows the format:
+
+You can note the OBR metadata Cave URL format:
{code}
http://[cave_server_hostname]:[http_service_port]/cave/[cave_repository_name]-repository.xml
{code}
-It means that you can register the Cave Repositories on a remote Karaf instance.
+It means that you can register the repositories on remote Apache Karaf instances.
-In the remote Karaf instance, you just have to install the obr feature and register the HTTP Wrapper repository.xml URL:
+In a remote Apache Karaf instance, you just have to install the obr feature and register the HTTP wrapper repository.xml URL:
{code}
karaf@other> features:install obr
karaf@other> obr:addurl http://cave_server:8181/cave/cave-repo-repository.xml
+karaf@other> obr:addurl http://cave_server:8181/cave/m2-repository.xml
{code}
h2. OSGi bundles access
-Cave HTTP Wrapper Service also provide the OSGi bundles via HTTP.
+Apache Karaf Cave HTTP wrapper service also provide the OSGi bundles binaries via HTTP.
-For instance, you have register the cave-repo Cave Repository in the OBR service:
+For instance, you have register the my-repository repository in the OBR service:
{code}
-karaf@root> cave:repository-install cave-repo
+karaf@root> cave:repository-install my-repository
{code}
So you have the following bundles available in the OBR service:
@@ -75,7 +78,7 @@ documentation: http://www.apache.org/
symbolicname: org.apache.servicemix.bundles.commons-dbcp
presentationname: Apache ServiceMix :: Bundles :: commons-dbcp
license: http://www.apache.org/licenses/LICENSE-2.0.txt
-uri: file:/home/jbonofre/apache-karaf-2.2.2/cave/cave-repo/org.apache.servicemix.bundles.commons-dbcp-1.4.0.1.jar
+uri: file:/home/user/apache-karaf-2.3.3/cave/cave-repo/org.apache.servicemix.bundles.commons-dbcp-1.4.0.1.jar
size: 159721
version: 1.4.0.1
Requires:
@@ -97,21 +100,21 @@ Capabilities:
package:{package=org.apache.commons.jocl, uses:=org.xml.sax.helpers,org.xml.sax, version=1.4.0}
{code}
-we can see that the URI is file:/home/jbonofre/apache-karaf-2.2.2/cave/cave-repo/org.apache.servicemix.bundles.commons-dbcp-1.4.0.1.jar.
+we can see that the URI is {{file:/home/user/apache-karaf-2.3.3/cave/cave-repo/org.apache.servicemix.bundles.commons-dbcp-1.4.0.1.jar.
-But the HTTP Wrapper Service also expose the bundle on:
+But the HTTP wrapper service also exposes the bundle on:
{code}
http://localhost:8181/cave/org.apache.servicemix.bundles.commons-dbcp-1.4.0.1.jar
{code}
-In fact, Cave handles bundle URI relatively to the repository.
+Actually, Apache Karaf Cave handles bundle URI relatively to the repository.
-So, it means that, if you register the cave-repo Cave Repository on a remote Karaf instance:
+So, it means that, if you register the my-repository repository on a remote Apache Karaf instance:
{code}
karaf@other> features:install obr
-karaf@other> obr:addurl http://cave_server:8181/cave/cave-repo-repository.xml
+karaf@other> obr:addurl http://cave_server:8181/cave/my-repository-repository.xml
{code}
you can take a look on the commons-dbcp details:
@@ -149,9 +152,9 @@ Capabilities:
package:{package=org.apache.commons.jocl, uses:=org.xml.sax.helpers,org.xml.sax, version=1.4.0}
{code}
-we can see that the URI is http://cave_server:8181/cave/org.apache.servicemix.bundles.commons-dbcp-1.4.0.1.jar.
+we can see that the URI is {{http://cave_server:8181/cave/org.apache.servicemix.bundles.commons-dbcp-1.4.0.1.jar}}.
-It means that we can use directly obr:deploy command:
+It means that we can use directly {{obr:deploy}} command:
{code}
karaf@root> obr:deploy org.apache.servicemix.bundles.commons-dbcp
http://git-wip-us.apache.org/repos/asf/karaf-cave/blob/1c360c70/manual/src/main/webapp/user-guide/index.conf
----------------------------------------------------------------------
diff --git a/manual/src/main/webapp/user-guide/index.conf b/manual/src/main/webapp/user-guide/index.conf
index 14f328e..111873c 100644
--- a/manual/src/main/webapp/user-guide/index.conf
+++ b/manual/src/main/webapp/user-guide/index.conf
@@ -1,11 +1,9 @@
h1. Apache Karaf Cave User Guide
-* [Installing Karaf Cave|/user-guide/installation]
-* [Cave Repository|/user-guide/cave-repository]
-* [Populate a Cave Repository|/user-guide/populate-repository]
-* [Proxy Repository|/user-guide/proxy-repository]
-* [OBR commands|/user-guide/obr-commands]
-* [HTTP Wrapper Service|/user-guide/http-wrapper]
-* [REST service|/user-guide/rest-service]
-* [Cave Client|/user-guide/client]
-* [Administrate Cave Server|/user-guide/administrate-cave]
\ No newline at end of file
+* [Installation|installation]
+* [Repository|cave-repository]
+* [Populate repository|populate-repository]
+* [Proxy repository|proxy-repository]
+* [OBR commands|obr-commands]
+* [HTTP wrapper service|/user-guide/http-wrapper]
+* [Administration|/user-guide/administrate-cave]
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/karaf-cave/blob/1c360c70/manual/src/main/webapp/user-guide/installation.conf
----------------------------------------------------------------------
diff --git a/manual/src/main/webapp/user-guide/installation.conf b/manual/src/main/webapp/user-guide/installation.conf
index bece2d5..19c7f20 100644
--- a/manual/src/main/webapp/user-guide/installation.conf
+++ b/manual/src/main/webapp/user-guide/installation.conf
@@ -1,46 +1,44 @@
h1. Installation
-This chapter describes how to install Apache Karaf Cave into an existing Karaf based installation.
+This chapter describes how to install Apache Karaf Cave into an existing Apache Karaf instance.
h2. Pre-installation requirements
-As Cave is a Karaf sub-project, you need a running Karaf instance.
+As Apache Karaf Cave is a Apache Karaf sub-project, it has to be installed into a running Apache Karaf instance.
-Karaf Cave is provided under a Karaf features descriptor. The easiest way to install is just to have an internet
-connection from the Karaf running instance.
+Apache Karaf Cave is available as Apache Karaf features. The easiest way to install is just to have an internet
+connection from the Apache Karaf running instance.
-h2. Registering Cave features
+h2. Registration of the Apache Karaf Cave features
-Karaf Cave is provided as a Karaf features XML descriptor.
-
-Simply register the Cave features URL in your Karaf instance:
+Simply register the Apache Karaf Cave features URL in your Apache Karaf instance:
{code}
-karaf@root> features:addurl mvn:org.apache.karaf.cave/apache-karaf-cave/2.3.0-SNAPSHOT/xml/features
+karaf@root> features:addurl mvn:org.apache.karaf.cave/apache-karaf-cave/2.3.0/xml/features
{code}
-Now you have Cave features available in your Karaf instance:
+Now Apache Karaf Cave features are available, ready to be installed:
{code}
karaf@root> features:list|grep -i cave
-[uninstalled] [2.3.0-SNAPSHOT ] cave-server repo-0
+[uninstalled ] [2.3.0 ] cave-server karaf-cave-2.3.0
{code}
-h3. Starting Cave OBR Server
+h3. Starting Apache Karaf Cave Server
-To start Cave, you have to install the cave-server feature:
+The Apache Karaf Cave Server is installed by the {{cave-server}} feature:
{code}
-karaf@root> features:install cave-obr-server
+karaf@root> features:install cave-server
{code}
-NB: installation of the cave-obr-server feature will install others features, such as obr, http, war, cxf. It could take
+NB: installation of the cave-server feature will install additional features, such as obr, http, war, CXF. It could take
several minutes depending of your network connection speed.
-The Cave commands are now available:
+New Apache Karaf Cave commands are now available:
{code}
karaf@root> cave:<TAB>
-cave:repository-create cave:repository-destroy cave:repositories-list cave:repository-populate
-cave:repository-proxy-url cave:repository-install cave:repository-scan cave:repository-upload-artifact
+cave:repositories-list cave:repository-create cave:repository-install cave:repository-populate
+cave:repository-proxy cave:repository-uninstall cave:repository-update cave:repository-upload-artifact
{code}
http://git-wip-us.apache.org/repos/asf/karaf-cave/blob/1c360c70/manual/src/main/webapp/user-guide/obr-commands.conf
----------------------------------------------------------------------
diff --git a/manual/src/main/webapp/user-guide/obr-commands.conf b/manual/src/main/webapp/user-guide/obr-commands.conf
index e898f6a..08ab222 100644
--- a/manual/src/main/webapp/user-guide/obr-commands.conf
+++ b/manual/src/main/webapp/user-guide/obr-commands.conf
@@ -1,19 +1,19 @@
-h1. OBR Commands
+h1. OBR commands
-To install a Cave Repository in the OBR service, you have to use:
+To install a repository in the OBR service, you have to use:
{code}
karaf@root> cave:repository-install cave-repo
{code}
-Now, you can see the Cave Repository OBR metadata register in the OBR service:
+Now, you can see the repository OBR metadata register in the OBR service:
{code}
karaf@root> obr:listurl
file:/home/jbonofre/apache-karaf-2.2.2/cave/cave-repo/repository.xml
{code}
-And the Cave Repository OSGi bundles are available in the OBR service:
+And the OSGi bundles present in the repository OSGi bundles are available in the OBR service:
{code}
karaf@root> obr:list
@@ -61,9 +61,9 @@ Capabilities:
package:{package=org.slf4j.helpers, version=1.6.1}
{code}
-NB: in Karaf, the OBR entry format is symbolicname,version
+NB: in Apache Karaf, the OBR entry format is symbolicname,version
-You have the detail of the OSGi bundle, especially the requirements and capabilities of the bundle.
+You have the details of the OSGi bundle, especially the requirements and capabilities of the bundle.
OBR is able to resolve the dependencies between bundles, depending of the requirements and capabilities of each bundle.
It's able to manage version, etc.
@@ -147,4 +147,4 @@ Deploying...done.
Done: the OBR has resolved the commons-dbcp requirements using the commons-pool capabilities and so installed the
commons-pool bundle.
-NB: in the obr:deploy command, if you don't mention the version, it will take the highly version available.
\ No newline at end of file
+NB: in the {{obr:deploy}} command, if you don't mention the version, it will take the highly version available.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/karaf-cave/blob/1c360c70/manual/src/main/webapp/user-guide/populate-repository.conf
----------------------------------------------------------------------
diff --git a/manual/src/main/webapp/user-guide/populate-repository.conf b/manual/src/main/webapp/user-guide/populate-repository.conf
index 1c5a1aa..678797e 100644
--- a/manual/src/main/webapp/user-guide/populate-repository.conf
+++ b/manual/src/main/webapp/user-guide/populate-repository.conf
@@ -1,63 +1,54 @@
-h1. Populate Cave Repository
+h1. Populate repository
+
+You can add new artifacts in a repository.
h2. Upload a single artifact
You can upload a single artifact into a Cave Repository:
{code}
-karaf@root> cave:repository-upload-artifact cave-repo file:/home/jbonofre/.m2/repository/org/apache/servicemix/bundles/org.apache.servicemix.bundles.asm/3.3_2/org.apache.servicemix.bundles.asm-3.3_2.jar
-karaf@root> cave:repository-upload-artifact cave-repo http://svn.apache.org/repos/asf/servicemix/m2-repo/org/apache/qpid/qpid-broker/0.8.0/qpid-broker-0.8.0.jar
+karaf@root> cave:repository-upload-artifact my-repository file:/home/user/.m2/repository/org/apache/servicemix/bundles/org.apache.servicemix.bundles.asm/3.3_2/org.apache.servicemix.bundles.asm-3.3_2.jar
+karaf@root> cave:repository-upload-artifact my-repository http://svn.apache.org/repos/asf/servicemix/m2-repo/org/apache/qpid/qpid-broker/0.8.0/qpid-broker-0.8.0.jar
{code}
You can also use Maven style URL:
{code}
-karaf@root> cave:repository-upload-artifact cave-repo mvn:org.apache.servicemix.bundles/org.apache.servicemix.bundles.ant/1.7.0_5
+karaf@root> cave:repository-upload-artifact my-repository mvn:org.apache.servicemix.bundles/org.apache.servicemix.bundles.ant/1.7.0_5
{code}
h3. Populate from an external repository
-You can also make a kind of "batch" population of your Cave Repository, using an external repository:
+You can also make a kind of "bulk" population of your repository, using an external repository:
{code}
-karaf@root> cave:repository-populate cave-repo file:/home/jbonofre/.m2/repository
+karaf@root> cave:repository-populate my-repository file:/home/user/.m2/repository
{code}
-Cave supports file: but also http: URL. It means that Cave is able to browse a remote repository and copy the artifacts.
+Apache Karaf Cave supports {{file:}} but also {{http:}} URL. It means that Apache Karaf Cave is able to browse a remote repository and copy the artifacts
+in your "local" repository.
-For instance, you can populate your Cave Repository using all Ant ServiceMix bundles present on the Central Maven
+For instance, you can populate your repository using all Ant ServiceMix bundles present on the Central Maven
repository:
{code}
-karaf@root> cave:repository-populate cave-repo http://repo1.maven.org/maven2/org/apache/servicemix/bundles/org.apache.servicemix.bundles.ant/
+karaf@root> cave:repository-populate my-repository http://repo1.maven.org/maven2/org/apache/servicemix/bundles/org.apache.servicemix.bundles.ant/
{code}
You can also populate with the whole Central Maven Repository:
{code}
-karaf@root> cave:repository-populate cave-repo http://repo1.maven.org/maven2
+karaf@root> cave:repository-populate my-repository http://repo1.maven.org/maven2
{code}
-WARNING: the Central Maven Repository is really huge and populating from the whole Maven Central Repository will take
+{warning}
+Maven Central repository is really huge and populating from the whole Maven Central Repository will take
very very long time. It's just for demonstration purpose.
+{warning}
-You can filter the artifacts that you want to pick up to populate the repository. The cave:repository-populate command accepts
+You can filter the artifacts that you want to pick up to populate the repository. The {{cave:repository-populate}} command accepts
a regex option for the filter. For instance, to pick up only joda-time version 2 artifact, you can run:
{code}
-karaf@root> cave:repository-populate --filter .*joda-time-2.* cave-repo http://repo2.maven.org/maven2/joda-time/joda-time
-{code}
-
-The cave:repository-populate command doesn't update the OBR metadata. You have to run:
-
-{code}
-karaf@root> cave:repository-scan cave-repo
-{code}
-
-to update the OBR metadata.
-
-If you want to update the OBR metadata at population time, you have to use the -u or --update option of the cave:repository-populate command:
-
-{code}
-karaf@root> cave:repository-populate -u cave-repo http://repo1.maven.org/maven2/org/apache/servicemix/bundles/org.apache.servicemix.bundles/
+karaf@root> cave:repository-populate --filter .*joda-time-2.* my-repository http://repo2.maven.org/maven2/joda-time/joda-time
{code}
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/karaf-cave/blob/1c360c70/manual/src/main/webapp/user-guide/proxy-repository.conf
----------------------------------------------------------------------
diff --git a/manual/src/main/webapp/user-guide/proxy-repository.conf b/manual/src/main/webapp/user-guide/proxy-repository.conf
index 9de136c..e4a0d74 100644
--- a/manual/src/main/webapp/user-guide/proxy-repository.conf
+++ b/manual/src/main/webapp/user-guide/proxy-repository.conf
@@ -1,21 +1,21 @@
-h1. Proxy A Repository
+h1. Proxy repository
-As you can [populate a Cave Repository|/user-guide/populate-repository], you can also proxy an "external" repository.
+As you can [populate repository|populate-repository], you can also proxy an "external" repository.
-It means that the artifacts stay on the remote repository, the Cave Repository generates the OBR metadata for the remote
-artifacts:
+It means that the artifacts stay on the remote repository, Apache Karaf Cave generates the OBR metadata in the local repository
+for the remote artifacts:
{code}
-karaf@root> cave:repository-proxy cave-repo http://repo1.maven.org/maven2/org/apache/servicemix/bundles/org.apache.servicemix.bundles.commons-lang/
+karaf@root> cave:repository-proxy my-repository http://repo1.maven.org/maven2/org/apache/servicemix/bundles/org.apache.servicemix.bundles.commons-lang/
{code}
-NB: the Cave Repository will only handle the OBR metadata, it doesn't monitor the remote repository. It means that you
-have to call cave:proxy-repository command each time that the remote repository change (new artifact, etc).
+NB: the Cave repository will only handle the OBR metadata, it doesn't monitor the remote repository. It means that you
+have to call the {{cave:proxy-repository}} command each time the remote repository change (new artifacts, etc).
-NB: a best practice is to create a Cave Repository dedicated for each proxied repository.
+NB: a best practice is to create a Cave repository dedicated for each proxied repository.
-The cave:proxy-repository command accepts the filter option, as the cave:populate-repository command:
+The {{cave:proxy-repository}} command accepts the filter option, as the {{cave:populate-repository}} command:
{code}
-cave:repository-proxy --filter .*joda-time-2.* cave-repo http://repo2.maven.org/maven2/joda-time/joda-time
+karaf@root> cave:repository-proxy --filter .*joda-time-2.* my-repository http://repo2.maven.org/maven2/joda-time/joda-time
{code}
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/karaf-cave/blob/1c360c70/manual/src/main/webapp/user-guide/rest-service.conf
----------------------------------------------------------------------
diff --git a/manual/src/main/webapp/user-guide/rest-service.conf b/manual/src/main/webapp/user-guide/rest-service.conf
deleted file mode 100644
index c02dffb..0000000
--- a/manual/src/main/webapp/user-guide/rest-service.conf
+++ /dev/null
@@ -1,7 +0,0 @@
-h1. REST Service
-
-Cave Server also provide a REST service API to be able to manipulate the Cave Server.
-
-By default, the REST Service is bound to http://localhost:8181/services/cave.
-
-TODO: complete with a presentation of the different path, produce, consume.
\ No newline at end of file