From 1eb278af89fa676c3e8efdcceb2153a0066a0de4 Mon Sep 17 00:00:00 2001 From: Olivier Lamy Date: Fri, 16 Sep 2011 14:33:21 +0000 Subject: [PATCH] start rest documentation git-svn-id: https://svn.apache.org/repos/asf/archiva/trunk@1171591 13f79535-47bb-0310-9956-ffa450edef68 --- .../src/site/apt/adminguide/web-services.apt | 99 +------------- .../apt/adminguide/webservices/rest.apt.vm | 43 ++++++ .../apt/adminguide/webservices/xml-rpc.apt | 127 ++++++++++++++++++ .../apt/customising/writing-consumer.apt.vm | 2 +- archiva-docs/src/site/site.xml | 5 +- .../services/AbstractArchivaRestTest.java | 7 + 6 files changed, 185 insertions(+), 98 deletions(-) create mode 100644 archiva-docs/src/site/apt/adminguide/webservices/rest.apt.vm create mode 100644 archiva-docs/src/site/apt/adminguide/webservices/xml-rpc.apt diff --git a/archiva-docs/src/site/apt/adminguide/web-services.apt b/archiva-docs/src/site/apt/adminguide/web-services.apt index 1b5ae1405..45f3cf731 100644 --- a/archiva-docs/src/site/apt/adminguide/web-services.apt +++ b/archiva-docs/src/site/apt/adminguide/web-services.apt @@ -2,6 +2,7 @@ Using Archiva Web Services ------ Maria Odea Ching + Olivier Lamy ------ 19 Mar 2009 ------ @@ -28,100 +29,6 @@ Using Archiva Web Services - Web services is a new feature for 1.2. Archiva exposes two types of services: administrative and search. A sample client - that shows how to access these services is provided in the source code. You can check out the module for the sample client at: - -+----+ -http://svn.apache.org/repos/asf/archiva/tags/archiva-1.2/archiva-modules/archiva-web/archiva-xmlrpc/archiva-xmlrpc-client/ -+----+ - - The SampleClient class shows how to connect to and invoke the Archiva web services. To execute the sample client, edit - the following configuration in the archiva-xmlrpc-client module's pom.xml: - -+-------------------------------------------------------------------------+ - - ... - - - - org.codehaus.mojo - exec-maven-plugin - - java - org.apache.archiva.web.xmlrpc.client.SampleClient - - - http://127.0.0.1:8080/archiva/xmlrpc - admin - ${password} - - - - - - -+-------------------------------------------------------------------------+ - - In the first \, set the url of the Archiva instance you are running but make sure that you have appended - at the end. For example if your Archiva instance is running in localhost and port 8080, then set it to http://localhost:8080/archiva/xmlrpc. - - The second \ corresponds to the username of the existing Archiva user that will be used to access the services while - the last \ is where you set the user's password. - - After configuring the pom, you can now run the sample client by executing <> in the command-line. You should be - able to see the list of managed and remote repositories, the list of database and repository consumers and more printed on the - command-line. - -* Administration Service - - In order for a user to be able to access the Administration services, the user must have a <> role in Archiva. - - The Administration Service exposes the following methods: - - [[1]] Boolean executeRepositoryScanner( String repoId ) - triggers the repository scanner to scan the specified repository. - - [[2]] Boolean executeDatabaseScanner() - triggers the database scanner to be executed. - - [[3]] List\ getAllDatabaseConsumers() - retrieves all the Archiva database consumers associated with the database scanning. - - [[4]] Boolean configureDatabaseConsumer( String consumerId, boolean enable ) - enables or disables the specified database consumer. - - [[5]] List\ getAllRepositoryConsumers() - retrieves all the Archiva repository consumers associated with the repository scanning. - - [[6]] Boolean configureRepositoryConsumer( String repoId, String consumerId, boolean enable ) - enables or disables the specified - repository consumer. - - [[7]] List\ getAllManagedRepositories() - retrieves all the managed repositories in Archiva. - - [[8]] List\ getAllRemoteRepositories() - retrieves all the remote repositories in Archiva. - - [[9]] Boolean deleteArtifact( String repoId, String groupId, String artifactId, String version ) - deletes the specified artifact from - the repository. - -* Search Service - - To access the Search Service, the user must have at least a <> role. - - The Search Service exposes the following methods: - - [[1]] List\ quickSearch( String queryString ) - search for the specified term. This behaves just like Archiva's Quick Search - from the web app. - - [[2]] List\ getArtifactByChecksum( String checksum ) - search for artifact(s) matching the specified checksum. This behaves like - the Find Artifact from the web app. - - [[3]] List\ getArtifactVersions( String groupId, String artifactId ) - retrieves all available versions of the artifact. - - [[4]] List\ getArtifactVersionsByDate( String groupId, String artifactId, String version, Date since ) - - - [[5]] List\ getDependencies( String groupId, String artifactId, String version ) - retrieves all the dependencies of the specified - artifact. This is the equivalent of the Dependencies tab in the Artifact Browse. - - [[6]] List\ getDependencyTree( String groupId, String artifactId, String version ) - - - [[7]] List\ getDependees( String groupId, String artifactId, String version ) - retrieves all the artifacts with a - dependency on the specified artifact. This is the equivalent of the Used By tab in the Artifact Browse. + Web services is a new feature for 1.2. Archiva exposes two types of services: administrative and search. More details : {{{./webservices/xml-rpc.html} Archiva Xml Rpc Services}} + Starting version 1.4, you can now use REST services : More details : {{{./webservices/rest.html} Archiva REST Services}} \ No newline at end of file diff --git a/archiva-docs/src/site/apt/adminguide/webservices/rest.apt.vm b/archiva-docs/src/site/apt/adminguide/webservices/rest.apt.vm new file mode 100644 index 000000000..06f35e46c --- /dev/null +++ b/archiva-docs/src/site/apt/adminguide/webservices/rest.apt.vm @@ -0,0 +1,43 @@ + ------ + Using REST Services + ------ + Olivier Lamy + ------ + 16 Sep 2011 + ------ + +~~ 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. + +~~ NOTE: For help with the syntax of this file, see: +~~ http://maven.apache.org/guides/mini/guide-apt-format.html + +Using REST Services + + Starting version 1.4, you can use some REST Services to manage your Apache Archiva instance and Search artifacts. + All samples here will use Apache CXF REST client API. By the way you can use some others REST client frameworks. + +* Search Service + + Authentication headers for connect to your Archiva instance : + + %{snippet|id=authz-header|url=http://svn.apache.org/repos/asf/archiva/trunk/archiva-modules/archiva-web/archiva-rest/archiva-rest-services/src/test/java/org/apache/archiva/rest/services/AbstractArchivaRestTest.java} + + + Get a Search Service Client : + + %{snippet|id=cxf-searchservice-creation|url=http://svn.apache.org/repos/asf/archiva/trunk/archiva-modules/archiva-web/archiva-rest/archiva-rest-services/src/test/java/org/apache/archiva/rest/services/AbstractArchivaRestTest.java} diff --git a/archiva-docs/src/site/apt/adminguide/webservices/xml-rpc.apt b/archiva-docs/src/site/apt/adminguide/webservices/xml-rpc.apt new file mode 100644 index 000000000..5d88f43f8 --- /dev/null +++ b/archiva-docs/src/site/apt/adminguide/webservices/xml-rpc.apt @@ -0,0 +1,127 @@ + ------ + Using Archiva Xml Rpc + ------ + Maria Odea Ching + ------ + 16 Sep 2011 + ------ + +~~ 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. + +~~ NOTE: For help with the syntax of this file, see: +~~ http://maven.apache.org/guides/mini/guide-apt-format.html + +Using Archiva Xml Rpc + + Web services is a new feature for 1.2. Archiva exposes two types of services: administrative and search. A sample client + that shows how to access these services is provided in the source code. You can check out the module for the sample client at: + ++----+ +http://svn.apache.org/repos/asf/archiva/tags/archiva-1.2/archiva-modules/archiva-web/archiva-xmlrpc/archiva-xmlrpc-client/ ++----+ + + The SampleClient class shows how to connect to and invoke the Archiva web services. To execute the sample client, edit + the following configuration in the archiva-xmlrpc-client module's pom.xml: + ++-------------------------------------------------------------------------+ + + ... + + + + org.codehaus.mojo + exec-maven-plugin + + java + org.apache.archiva.web.xmlrpc.client.SampleClient + + + http://127.0.0.1:8080/archiva/xmlrpc + admin + ${password} + + + + + + ++-------------------------------------------------------------------------+ + + In the first \, set the url of the Archiva instance you are running but make sure that you have appended + at the end. For example if your Archiva instance is running in localhost and port 8080, then set it to http://localhost:8080/archiva/xmlrpc. + + The second \ corresponds to the username of the existing Archiva user that will be used to access the services while + the last \ is where you set the user's password. + + After configuring the pom, you can now run the sample client by executing <> in the command-line. You should be + able to see the list of managed and remote repositories, the list of database and repository consumers and more printed on the + command-line. + +* Administration Service + + In order for a user to be able to access the Administration services, the user must have a <> role in Archiva. + + The Administration Service exposes the following methods: + + [[1]] Boolean executeRepositoryScanner( String repoId ) - triggers the repository scanner to scan the specified repository. + + [[2]] Boolean executeDatabaseScanner() - triggers the database scanner to be executed. + + [[3]] List\ getAllDatabaseConsumers() - retrieves all the Archiva database consumers associated with the database scanning. + + [[4]] Boolean configureDatabaseConsumer( String consumerId, boolean enable ) - enables or disables the specified database consumer. + + [[5]] List\ getAllRepositoryConsumers() - retrieves all the Archiva repository consumers associated with the repository scanning. + + [[6]] Boolean configureRepositoryConsumer( String repoId, String consumerId, boolean enable ) - enables or disables the specified + repository consumer. + + [[7]] List\ getAllManagedRepositories() - retrieves all the managed repositories in Archiva. + + [[8]] List\ getAllRemoteRepositories() - retrieves all the remote repositories in Archiva. + + [[9]] Boolean deleteArtifact( String repoId, String groupId, String artifactId, String version ) - deletes the specified artifact from + the repository. + +* Search Service + + To access the Search Service, the user must have at least a <> role. + + The Search Service exposes the following methods: + + [[1]] List\ quickSearch( String queryString ) - search for the specified term. This behaves just like Archiva's Quick Search + from the web app. + + [[2]] List\ getArtifactByChecksum( String checksum ) - search for artifact(s) matching the specified checksum. This behaves like + the Find Artifact from the web app. + + [[3]] List\ getArtifactVersions( String groupId, String artifactId ) - retrieves all available versions of the artifact. + + [[4]] List\ getArtifactVersionsByDate( String groupId, String artifactId, String version, Date since ) - + + [[5]] List\ getDependencies( String groupId, String artifactId, String version ) - retrieves all the dependencies of the specified + artifact. This is the equivalent of the Dependencies tab in the Artifact Browse. + + [[6]] List\ getDependencyTree( String groupId, String artifactId, String version ) - + + [[7]] List\ getDependees( String groupId, String artifactId, String version ) - retrieves all the artifacts with a + dependency on the specified artifact. This is the equivalent of the Used By tab in the Artifact Browse. + diff --git a/archiva-docs/src/site/apt/customising/writing-consumer.apt.vm b/archiva-docs/src/site/apt/customising/writing-consumer.apt.vm index cc1c74195..ed2419641 100644 --- a/archiva-docs/src/site/apt/customising/writing-consumer.apt.vm +++ b/archiva-docs/src/site/apt/customising/writing-consumer.apt.vm @@ -4,7 +4,7 @@ Maria Odea Ching Olivier Lamy ------ - 06 Sep 2011 + 16 Sep 2011 ------ ~~ Licensed to the Apache Software Foundation (ASF) under one diff --git a/archiva-docs/src/site/site.xml b/archiva-docs/src/site/site.xml index dbe8bc9a5..0007c0a52 100644 --- a/archiva-docs/src/site/site.xml +++ b/archiva-docs/src/site/site.xml @@ -80,7 +80,10 @@ - + + + + diff --git a/archiva-modules/archiva-web/archiva-rest/archiva-rest-services/src/test/java/org/apache/archiva/rest/services/AbstractArchivaRestTest.java b/archiva-modules/archiva-web/archiva-rest/archiva-rest-services/src/test/java/org/apache/archiva/rest/services/AbstractArchivaRestTest.java index 82f496e9f..e663327d5 100644 --- a/archiva-modules/archiva-web/archiva-rest/archiva-rest-services/src/test/java/org/apache/archiva/rest/services/AbstractArchivaRestTest.java +++ b/archiva-modules/archiva-web/archiva-rest/archiva-rest-services/src/test/java/org/apache/archiva/rest/services/AbstractArchivaRestTest.java @@ -44,8 +44,15 @@ public abstract class AbstractArchivaRestTest { // START SNIPPET: authz-header + // guest with an empty password public String guestAuthzHeader = "Basic " + org.apache.cxf.common.util.Base64Utility.encode( ( "guest" + ":" ).getBytes() ); + + // with an other login/password + //public String authzHeader = + // "Basic " + org.apache.cxf.common.util.Base64Utility.encode( ( "login" + ":password" ).getBytes() ); + + // END SNIPPET: authz-header @Override