[KARAF-871] Update Cave documentation git-svn-id: https://svn.apache.org/repos/asf/karaf/cave/trunk@1510542 13f79535-47bb-0310-9956-ffa450edef68
Project: http://git-wip-us.apache.org/repos/asf/karaf-cave/repo Commit: http://git-wip-us.apache.org/repos/asf/karaf-cave/commit/fa5fcde4 Tree: http://git-wip-us.apache.org/repos/asf/karaf-cave/tree/fa5fcde4 Diff: http://git-wip-us.apache.org/repos/asf/karaf-cave/diff/fa5fcde4 Branch: refs/heads/master Commit: fa5fcde4ffbf0c4e31c09e734cc7939b3c2bd84a Parents: d499da1 Author: jbonofre <jbonofre@13f79535-47bb-0310-9956-ffa450edef68> Authored: Mon Aug 5 15:13:48 2013 +0000 Committer: jbonofre <jbonofre@13f79535-47bb-0310-9956-ffa450edef68> Committed: Mon Aug 5 15:13:48 2013 +0000 ---------------------------------------------------------------------- manual/src/main/webapp/manual.conf | 2 +- .../webapp/user-guide/administrate-cave.conf | 9 ++++ .../webapp/user-guide/adminsitrate-cave.conf | 9 ---- .../main/webapp/user-guide/cave-repository.conf | 22 ++++---- .../main/webapp/user-guide/http-wrapper.conf | 4 +- .../main/webapp/user-guide/installation.conf | 4 +- .../main/webapp/user-guide/obr-commands.conf | 4 +- .../webapp/user-guide/populate-repository.conf | 24 ++++----- .../webapp/user-guide/proxy-repository.conf | 4 +- .../server/command/RepositoryProxyCommand.java | 53 ++++++++++++++++++++ .../command/RepositoryProxyUrlCommand.java | 53 -------------------- .../OSGI-INF/blueprint/cave-server-commands.xml | 4 +- 12 files changed, 96 insertions(+), 96 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/karaf-cave/blob/fa5fcde4/manual/src/main/webapp/manual.conf ---------------------------------------------------------------------- diff --git a/manual/src/main/webapp/manual.conf b/manual/src/main/webapp/manual.conf index c47922f..4bfbee6 100644 --- a/manual/src/main/webapp/manual.conf +++ b/manual/src/main/webapp/manual.conf @@ -14,7 +14,7 @@ User Guide {div} {div:class=copyright-section} -Copyright 2011 The Apache Software Foundation +Copyright 2013 The Apache Software Foundation The PDF format of the Karaf Manual has been generated by Prince XML (http://www.princexml.com). {div} http://git-wip-us.apache.org/repos/asf/karaf-cave/blob/fa5fcde4/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 new file mode 100644 index 0000000..89126e2 --- /dev/null +++ b/manual/src/main/webapp/user-guide/administrate-cave.conf @@ -0,0 +1,9 @@ +h1. Administrate Cave Server + +When you install the Cave Server, it binds a set of JMX MBeans. + +These MBeans allow you to monitore and administrate the Cave Server. + +It means that you can manipulate Cave Repositories using a JMX client. + +TODO: complete with the MBeans detail. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/karaf-cave/blob/fa5fcde4/manual/src/main/webapp/user-guide/adminsitrate-cave.conf ---------------------------------------------------------------------- diff --git a/manual/src/main/webapp/user-guide/adminsitrate-cave.conf b/manual/src/main/webapp/user-guide/adminsitrate-cave.conf deleted file mode 100644 index 89126e2..0000000 --- a/manual/src/main/webapp/user-guide/adminsitrate-cave.conf +++ /dev/null @@ -1,9 +0,0 @@ -h1. Administrate Cave Server - -When you install the Cave Server, it binds a set of JMX MBeans. - -These MBeans allow you to monitore and administrate the Cave Server. - -It means that you can manipulate Cave Repositories using a JMX client. - -TODO: complete with the MBeans detail. \ No newline at end of file http://git-wip-us.apache.org/repos/asf/karaf-cave/blob/fa5fcde4/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 e43c944..9f6a526 100644 --- a/manual/src/main/webapp/user-guide/cave-repository.conf +++ b/manual/src/main/webapp/user-guide/cave-repository.conf @@ -18,10 +18,10 @@ storage.location=cave h2. Create a Cave Repository -The cave:create-repository command create a Cave Repository: +The cave:repository-create command creates a Cave Repository: {code} -karaf@root> cave:create-repository cave-repo +karaf@root> cave:repository-create cave-repo {code} A Cave Repository is identified by a name, cave-repo in our example. @@ -37,14 +37,14 @@ If you want to use an existing directory, and avoid Cave to create one in the st --location option: {code} -karaf@root> cave:create-repository -l /home/jbonofre/.m2/repository m2 +karaf@root> cave:repository-create -l /home/jbonofre/.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: {code} -karaf@root> cave:create-repository -s -l /home/jbonofre/.m2/repository m2 +karaf@root> cave:repository-create -s -l /home/jbonofre/.m2/repository m2 {code} In the same way, you can register the Cave Repository in the OBR service directly at creation time. For instance, you @@ -55,7 +55,7 @@ can combine the three options to: 3. register the Cave repository in the OBR service {code} -karaf@root> cave:create-repository -s -r -l /home/jbonofre/.m2/repository m2 +karaf@root> cave:repository-create -s -r -l /home/jbonofre/.m2/repository m2 {code} h2. List of Cave Repositories @@ -63,9 +63,9 @@ h2. List of Cave Repositories You can list the Cave Repositories: {code} -karaf@root> cave:list-repositories +karaf@root> cave:repositories-list Name Location -[cave-repo] [/home/jbonofre/apache-karaf-2.2.2/cave/cave-repo] +[cave-repo] [/home/jbonofre/apache-karaf-2.3.1/cave/cave-repo] [m2] [/home/jbonofre/.m2/repository] {code} @@ -74,7 +74,7 @@ h2. Remove and destroy a Cave Repository You can remove a Cave Repository from the repositories registry: {code} -karaf@root> cave:remove-repository cave-repo +karaf@root> cave:repository-uninstall cave-repo {code} The Cave Repository storage won't be removed. It means that the artifacts will stay in the storage folder. @@ -82,7 +82,7 @@ The Cave Repository storage won't be removed. It means that the artifacts will s If you want to destroy a Cave Repository, including the artifacts and the storage folder, you have to use: {code} -karaf@root> cave:destroy-repository cave-repo +karaf@root> cave:repository-destroy cave-repo {code} h2. Generate OBR metadata @@ -90,7 +90,7 @@ h2. Generate OBR metadata You can generate the OBR metadata: {code} -karaf@root> cave:scan-repository cave-repo +karaf@root> cave:repository-scan cave-repo {code} Cave will scan the Cave Repository storage, looking for OSGi bundle, and generate the OBR metadata. @@ -100,7 +100,7 @@ h2. Register Cave Repository in the OBR service Once you have generated the OBR metadata, you can register the Cave Repository in the OBR service: {code} -karaf@root> cave:register-repository cave-repo +karaf@root> cave:repository-install cave-repo {code} You are now ready to use the [OBR commands|/user-guide/obr-command]. http://git-wip-us.apache.org/repos/asf/karaf-cave/blob/fa5fcde4/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 99270dc..301cb98 100644 --- a/manual/src/main/webapp/user-guide/http-wrapper.conf +++ b/manual/src/main/webapp/user-guide/http-wrapper.conf @@ -9,7 +9,7 @@ h2. OBR metadata access Assuming that you have the following Cave Repositories: {code} -karaf@root> cave:list-repositories +karaf@root> cave:repositories-list Name Location [cave-repo] [/home/jbonofre/apache-karaf-2.2.2/cave/cave-repo] [m2] [/home/jbonofre/.m2/repository] @@ -51,7 +51,7 @@ Cave HTTP Wrapper Service also provide the OSGi bundles via HTTP. For instance, you have register the cave-repo Cave Repository in the OBR service: {code} -karaf@root> cave:register-repository cave-repo +karaf@root> cave:repository-install cave-repo {code} So you have the following bundles available in the OBR service: http://git-wip-us.apache.org/repos/asf/karaf-cave/blob/fa5fcde4/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 82ab4d2..bece2d5 100644 --- a/manual/src/main/webapp/user-guide/installation.conf +++ b/manual/src/main/webapp/user-guide/installation.conf @@ -41,6 +41,6 @@ The Cave commands are now available: {code} karaf@root> cave:<TAB> -cave:create-repository cave:destroy-repository cave:list-repositories cave:populate-repository -cave:proxy-repository cave:register-repository cave:scan-repository cave:upload-artifact +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 {code} http://git-wip-us.apache.org/repos/asf/karaf-cave/blob/fa5fcde4/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 77f9a40..e898f6a 100644 --- a/manual/src/main/webapp/user-guide/obr-commands.conf +++ b/manual/src/main/webapp/user-guide/obr-commands.conf @@ -1,9 +1,9 @@ h1. OBR Commands -To register a Cave Repository in the OBR service, you have to use: +To install a Cave Repository in the OBR service, you have to use: {code} -karaf@root> cave:register-repository cave-repo +karaf@root> cave:repository-install cave-repo {code} Now, you can see the Cave Repository OBR metadata register in the OBR service: http://git-wip-us.apache.org/repos/asf/karaf-cave/blob/fa5fcde4/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 7faef1a..1c5a1aa 100644 --- a/manual/src/main/webapp/user-guide/populate-repository.conf +++ b/manual/src/main/webapp/user-guide/populate-repository.conf @@ -5,14 +5,14 @@ h2. Upload a single artifact You can upload a single artifact into a Cave Repository: {code} -karaf@root> cave: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: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 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 {code} You can also use Maven style URL: {code} -karaf@root> cave:upload-artifact cave-repo mvn:org.apache.servicemix.bundles/org.apache.servicemix.bundles.ant/1.7.0_5 +karaf@root> cave:repository-upload-artifact cave-repo mvn:org.apache.servicemix.bundles/org.apache.servicemix.bundles.ant/1.7.0_5 {code} h3. Populate from an external repository @@ -20,7 +20,7 @@ h3. Populate from an external repository You can also make a kind of "batch" population of your Cave Repository, using an external repository: {code} -karaf@root> cave:populate-repository cave-repo file:/home/jbonofre/.m2/repository +karaf@root> cave:repository-populate cave-repo file:/home/jbonofre/.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. @@ -29,35 +29,35 @@ For instance, you can populate your Cave Repository using all Ant ServiceMix bun repository: {code} -karaf@root> cave:populate-repository cave-repo http://repo1.maven.org/maven2/org/apache/servicemix/bundles/org.apache.servicemix.bundles.ant/ +karaf@root> cave:repository-populate cave-repo 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:populate-repository cave-repo http://repo1.maven.org/maven2 +karaf@root> cave:repository-populate cave-repo http://repo1.maven.org/maven2 {code} WARNING: the Central Maven Repository is really huge and populating from the whole Maven Central Repository will take very very long time. It's just for demonstration purpose. -You can filter the artifacts that you want to pick up to populate the repository. The cave:populate-repository 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} -cave:populate-repository --filter .*joda-time-2.* cave-repo http://repo2.maven.org/maven2/joda-time/joda-time +karaf@root> cave:repository-populate --filter .*joda-time-2.* cave-repo http://repo2.maven.org/maven2/joda-time/joda-time {code} -The cave:populate-repository command doesn't update the OBR metadata. You have to run: +The cave:repository-populate command doesn't update the OBR metadata. You have to run: {code} -karaf@root> cave:scan-repository cave-repo +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:populate-repository command: +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:populate-repository -u cave-repo http://repo1.maven.org/maven2/org/apache/servicemix/bundles/org.apache.servicemix.bundles/ +karaf@root> cave:repository-populate -u cave-repo http://repo1.maven.org/maven2/org/apache/servicemix/bundles/org.apache.servicemix.bundles/ {code} \ No newline at end of file http://git-wip-us.apache.org/repos/asf/karaf-cave/blob/fa5fcde4/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 c8b9b85..9de136c 100644 --- a/manual/src/main/webapp/user-guide/proxy-repository.conf +++ b/manual/src/main/webapp/user-guide/proxy-repository.conf @@ -6,7 +6,7 @@ It means that the artifacts stay on the remote repository, the Cave Repository g artifacts: {code} -karaf@root> cave:proxy-repository cave-repo http://repo1.maven.org/maven2/org/apache/servicemix/bundles/org.apache.servicemix.bundles.commons-lang/ +karaf@root> cave:repository-proxy cave-repo 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 @@ -17,5 +17,5 @@ NB: a best practice is to create a Cave Repository dedicated for each proxied re The cave:proxy-repository command accepts the filter option, as the cave:populate-repository command: {code} -cave:proxy-repository --filter .*joda-time-2.* cave-repo http://repo2.maven.org/maven2/joda-time/joda-time +cave:repository-proxy --filter .*joda-time-2.* cave-repo 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/fa5fcde4/server/command/src/main/java/org/apache/karaf/cave/server/command/RepositoryProxyCommand.java ---------------------------------------------------------------------- diff --git a/server/command/src/main/java/org/apache/karaf/cave/server/command/RepositoryProxyCommand.java b/server/command/src/main/java/org/apache/karaf/cave/server/command/RepositoryProxyCommand.java new file mode 100644 index 0000000..b3664d9 --- /dev/null +++ b/server/command/src/main/java/org/apache/karaf/cave/server/command/RepositoryProxyCommand.java @@ -0,0 +1,53 @@ +/* + * 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. + */ +package org.apache.karaf.cave.server.command; + +import org.apache.felix.gogo.commands.Argument; +import org.apache.felix.gogo.commands.Command; +import org.apache.felix.gogo.commands.Option; +import org.apache.karaf.cave.server.api.CaveRepository; + +import java.net.URL; + +/** + * Add an URL to proxy in the Karaf Cave repository. + */ +@Command(scope = "cave", name = "repository-proxy", description = "Proxy a given URL in the Karaf Cave repository") +public class RepositoryProxyCommand extends CaveRepositoryCommandSupport { + + @Argument(index = 0, name = "name", description = "The repository proxying the URL", required = true, multiValued = false) + String name = null; + + @Argument(index = 1, name = "URL", description = "The URL to proxy", required = true, multiValued = false) + String url = null; + + @Option(name = "-nu", aliases = { "--no-update", "--no-refresh", "--no-register" }, description = "No refresh of the OBR URLs", required = false, multiValued = false) + boolean noUpdate = false; + + @Option(name = "-f", aliases = { "--filter" }, description = "Regex filter on the artifacts URL", required = false, multiValued = false) + String filter; + + protected Object doExecute() throws Exception { + CaveRepository repository = getExistingRepository(name); + repository.proxy(new URL(url), filter); + if (!noUpdate) { + getCaveRepositoryService().install(name); + } + return null; + } + +} http://git-wip-us.apache.org/repos/asf/karaf-cave/blob/fa5fcde4/server/command/src/main/java/org/apache/karaf/cave/server/command/RepositoryProxyUrlCommand.java ---------------------------------------------------------------------- diff --git a/server/command/src/main/java/org/apache/karaf/cave/server/command/RepositoryProxyUrlCommand.java b/server/command/src/main/java/org/apache/karaf/cave/server/command/RepositoryProxyUrlCommand.java deleted file mode 100644 index d52948f..0000000 --- a/server/command/src/main/java/org/apache/karaf/cave/server/command/RepositoryProxyUrlCommand.java +++ /dev/null @@ -1,53 +0,0 @@ -/* - * 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. - */ -package org.apache.karaf.cave.server.command; - -import org.apache.felix.gogo.commands.Argument; -import org.apache.felix.gogo.commands.Command; -import org.apache.felix.gogo.commands.Option; -import org.apache.karaf.cave.server.api.CaveRepository; - -import java.net.URL; - -/** - * Add an URL to proxy in the Karaf Cave repository. - */ -@Command(scope = "cave", name = "repository-proxy-url", description = "Proxy a given URL in the Karaf Cave repository") -public class RepositoryProxyUrlCommand extends CaveRepositoryCommandSupport { - - @Argument(index = 0, name = "name", description = "The repository proxying the URL", required = true, multiValued = false) - String name = null; - - @Argument(index = 1, name = "URL", description = "The URL to proxy", required = true, multiValued = false) - String url = null; - - @Option(name = "-nu", aliases = { "--no-update", "--no-refresh", "--no-register" }, description = "No refresh of the OBR URLs", required = false, multiValued = false) - boolean noUpdate = false; - - @Option(name = "-f", aliases = { "--filter" }, description = "Regex filter on the artifacts URL", required = false, multiValued = false) - String filter; - - protected Object doExecute() throws Exception { - CaveRepository repository = getExistingRepository(name); - repository.proxy(new URL(url), filter); - if (!noUpdate) { - getCaveRepositoryService().install(name); - } - return null; - } - -} http://git-wip-us.apache.org/repos/asf/karaf-cave/blob/fa5fcde4/server/command/src/main/resources/OSGI-INF/blueprint/cave-server-commands.xml ---------------------------------------------------------------------- diff --git a/server/command/src/main/resources/OSGI-INF/blueprint/cave-server-commands.xml b/server/command/src/main/resources/OSGI-INF/blueprint/cave-server-commands.xml index 0f6155a..193c6ed 100644 --- a/server/command/src/main/resources/OSGI-INF/blueprint/cave-server-commands.xml +++ b/server/command/src/main/resources/OSGI-INF/blueprint/cave-server-commands.xml @@ -50,8 +50,8 @@ <null/> </completers> </command> - <command name="cave/repository-proxy-url"> - <action class="org.apache.karaf.cave.server.command.RepositoryProxyUrlCommand"> + <command name="cave/repository-proxy"> + <action class="org.apache.karaf.cave.server.command.RepositoryProxyCommand"> <property name="caveRepositoryService" ref="caveRepositoryService"/> </action> <completers>
