| ----- |
| REST Services |
| ----- |
| Olivier Lamy |
| ----- |
| 2012-01-19 |
| ----- |
| |
| ~~ 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 |
| |
| Expose Rest Services |
| |
| |
| The {{{http://cxf.apache.org}Apache CXF}} is used to expose some classes/methods as REST Services. |
| |
| Services use the standard interface/implementation pattern: |
| |
| * interfaces and beans are located in archiva-rest-api maven module |
| |
| * implementation are located in archiva-rest-services maven module |
| |
| [] |
| |
| %{toc} |
| |
| * Steps to expose your class as a REST Service. |
| |
| Here all the steps to expose a new class as a REST service. |
| |
| ** Interface and data beans |
| |
| All interfaces and data beans are added in the module archiva-rest-api: |
| |
| * interface in the package: org.apache.archiva.rest.api.services . |
| |
| * data beans in the package: org.apache.archiva.rest.api.model . |
| |
| [] |
| |
| *** Beans |
| |
| As we want to be able to expose result as json or xml type, all beans use javax.xml.bind.annotation root element : |
| |
| +--------------------- |
| @XmlRootElement( name = "artifact" ) |
| public class Artifact |
| implements Serializable |
| |
| All services will be able to return json or xml |
| @Produces( { MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML } ) |
| +--------------------- |
| |
| *** JAXRS annotations |
| |
| As we use interfaces/implementations pattern jaxrs annotations are only in interfaces level. |
| |
| +--------------------- |
| @Path( "/managedRepositoriesService/" ) |
| public interface ManagedRepositoriesService |
| { |
| // simple GET method no parameter |
| @Path( "getManagedRepositories" ) |
| @GET |
| @Produces( { MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML } ) |
| List<ManagedRepository> getManagedRepositories() |
| throws ArchivaRestServiceException; |
| |
| // GET method with a path parameter |
| @Path( "getManagedRepository/{repositoryId}" ) |
| @GET |
| @Produces( { MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML } ) |
| @RedbackAuthorization( permissions = ArchivaRoleConstants.OPERATION_MANAGE_CONFIGURATION ) |
| ManagedRepository getManagedRepository( @PathParam( "repositoryId" ) String repositoryId ) |
| throws ArchivaRestServiceException; |
| |
| // POST method to pass a data bean |
| @Path( "addManagedRepository" ) |
| @POST |
| @Consumes( { MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML } ) |
| @Produces( { MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML } ) |
| @RedbackAuthorization( permissions = ArchivaRoleConstants.OPERATION_MANAGE_CONFIGURATION ) |
| ManagedRepository addManagedRepository( ManagedRepository managedRepository ) |
| throws ArchivaRestServiceException; |
| +--------------------- |
| |
| ** CXF/Spring configuration |
| |
| REST services implementations are marked with the Spring annotation @Service |
| |
| +--------------------- |
| package org.apache.archiva.rest.services; |
| ...... |
| @Service( "managedRepositoriesService#rest" ) |
| public class DefaultManagedRepositoriesService |
| extends AbstractRestService |
| implements ManagedRepositoriesService |
| +--------------------- |
| |
| Spring beans are declared as REST/CXF services in the Spring configuration |
| |
| +--------------------- |
| <jaxrs:server id="archivaServices" address="/archivaServices"> |
| ..... |
| <jaxrs:serviceBeans> |
| <ref bean="managedRepositoriesService#rest"/> |
| </jaxrs:serviceBeans> |
| ..... |
| </jaxrs:server> |
| |
| Note as we use @Service annotation package scanning must declared in spring configuration |
| |
| <beans xmlns="http://www.springframework.org/schema/beans" |
| xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" |
| xmlns:context="http://www.springframework.org/schema/context" |
| xsi:schemaLocation="http://www.springframework.org/schema/context |
| http://www.springframework.org/schema/context/spring-context-3.0.xsd ...."> |
| ... |
| <context:annotation-config/> |
| <context:component-scan |
| base-package="org.apache.archiva.rest.services"/> |
| |
| ... |
| </beans> |
| +--------------------- |
| |
| CXF servlet is declared as: |
| |
| +--------------------- |
| <servlet> |
| <servlet-name>CXFServlet</servlet-name> |
| <servlet-class>org.apache.cxf.transport.servlet.CXFServlet</servlet-class> |
| <load-on-startup>1</load-on-startup> |
| </servlet> |
| |
| <servlet-mapping> |
| <servlet-name>CXFServlet</servlet-name> |
| <url-pattern>/restServices/*</url-pattern> |
| </servlet-mapping> |
| +--------------------- |
| |
| So as it, REST services are availble in the following url <<restServices/archivaServices/>>. |
| |
| ** Redback security annotation |
| |
| Some REST methods need some karma, so to prevent anonymous access methods can be marked as it: |
| |
| +--------------------- |
| |
| @RedbackAuthorization( permissions = ArchivaRoleConstants.OPERATION_MANAGE_CONFIGURATION ) |
| ManagedRepository addManagedRepository( ManagedRepository managedRepository ) |
| throws ArchivaRestServiceException; |
| +--------------------- |
| |
| This method will need the current user to have the operation manage-configuration level. |
| |
| For more details, have a look at {{{http://archiva.apache.org/redback/integration/rest.html}Redback REST}}. |
| |
| |
| |
| |
| |
| |
| |