Servi�os RESTful com Apache CXF e Camel

Neste artigo vamos abordar uma nova arquitetura para construç�o de serviços. Estamos falando de serviços Restful baseados nos princ�pios arquiteturais definidos por REST. Utilizaremos os frameworks Apache CXF e Apache Camel para demonstrar como � simples implementar serviços que seguem o padr�o Restful constru�dos com a especificaç�o JAX-RS.

Figura 1. Operaç�es HTTP para serviços Restful

De forma bem simples, REST (Representation State Transfer) � um conjunto de princ�pios. A promessa � que uma vez seguidos esse conjunto de princ�pios enquanto voc� desenha a sua aplicaç�o, ao final voc� ter� um sistema que explora e faz uso de todo o benef�cio da arquitetura Web. Vamos ver rapidamente quais s�o os princ�pios:

Endereçamento. � a ideia que todo objeto ou recurso no seu sistema � pass�vel de ser encontrado atrav�s de um identificador �nico. Na web qualquer recurso est� associado a um endereço URI (Uniform Resource Identifier). Uma URL � apenas um tipo de URI. Uma URI tem a seguinte forma: scheme://host:port/path?queryString#fragment. Veja o seguinte exemplo: http://example.com/customers?cpf=1234321. Ela n�o poderia representar facilmente um cliente? O retorno � chamada dessa URI poderia ser um documento com uma s�rie de �links� para outras informaç�es do mesmo cliente ou outras entidades ou pessoas relacionadas a esse cliente.
Interface Uniforme. se existem recursos com endereços, que tal acess�-los atrav�s de um conjunto bem definido de operaç�es ou aç�es? Em HTTP s�o chamados de verbos (GET, POST, PUT, DELETE etc.).
Orientaç�o � Representaç�o. em cada operaç�o (GET, POST, PUT etc.) um estado ou representaç�o de um recurso � passado ou recebido. Em HTTP, essa representaç�o pode ser JSON, XML, texto ou outros. Cada tipo de conte�do compartilhado � associado a um �MIME type�. Uma mesma URI pode transferir conte�do em XML ou JSON.
Aus�ncia de estado. isso quer dizer que o servidor n�o guarda estado algum sobre o cliente. Se houver necessidade de algum tipo de sess�o, o cliente ser� respons�vel por ela.
HATEOAS (Hypermedia As The Engine Of Application State). em uma soluç�o centrada em documentos, cada documento pode conter refer�ncias para a pr�xima interaç�o com o servidor. Imagine que voc� est� consultando uma lista grande de clientes. Na primeira transfer�ncia de estado, pode haver um link para obtenç�o da pr�xima �pagina� contendo mais informaç�es de clientes.

Seguindo esses princ�pios, conseguimos ter soluç�es com comportamentos bem definidos, escal�veis e mais facilmente interoper�veis j� que consumir uma URL � algo facilmente realizado por qualquer cliente HTTP..

Um serviço Restful � uma aplicaç�o constru�da dentro dos princ�pios explicados. Existe uma API Java conhecida por JAX-RS que pretende trazer a mesma facilidade para construç�o de serviços Restful que JAX-WS traz para a construç�o de WebServices.

Vamos agora examinar um exemplo muito simples de construç�o de serviço Restful utilizando o Apache CXF e Apache Camel. No nosso exemplo, o CXF � o respons�vel pela execuç�o do servidor HTTP, caracter�sticas de transporte e ciclo de vida do serviço. O Apache Camel ser� a implementaç�o do serviço ger�nciado pelo CXF. Vamos dar uma olhada no serviço HelloWorldServiceRest na listagem 1.


@Path("/helloworldservice")
public class HelloWorldServiceRest {

	@GET
	@Path("/hello")
	@Produces("application/json")
	public String hello(@QueryParam("nome") String name) {
		return null;
	}

}

Listagem 1. Interface do Serviço Restful

� bem simples. Vemos uma primeira anotaç�o @Path, determinando parte da url que d� acesso ao nosso serviço. Uma operaç�o chamada �hello� anotada com @GET indicando que o verbo GET � suportado. @Produces indica o MIME type do retorno desse m�todo. @QueryParam captura o par�metro nome passado na URL. Veja um exemplo de chamada dessa operaç�o que pode ser facilmente testado em um navegador da internet: http://localhost:8090/hello/helloworldservice/hello?nome=John.

Na listagem 2 vemos o nosso arquivo de configuraç�o do Spring que inicia o nosso serviço no endereço f�sico �http://localhost:8090/hello�. Atrav�s do namespace cxf, temos acesso ao bean rsServer que utiliza a classe da listagem 1 para iniciar nosso serviço na porta configurada.


<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:jaxws="http://cxf.apache.org/jaxws"
    xmlns:cxf="http://camel.apache.org/schema/cxf"
    xmlns="http://www.springframework.org/schema/beans"
    xmlns:camel="http://camel.apache.org/schema/spring"
    xsi:schemaLocation="
    	http://camel.apache.org/schema/spring 
        http://camel.apache.org/schema/spring/camel-spring.xsd
    	http://camel.apache.org/schema/cxf 
        http://camel.apache.org/schema/cxf/camel-cxf.xsd
		http://www.springframework.org/schema/beans 
        http://www.springframework.org/schema/beans/spring-beans.xsd
		http://cxf.apache.org/jaxws
		http://cxf.apache.org/schemas/jaxws.xsd" >

	<cxf:rsServer id="server" address="http://localhost:8090/hello" 
    serviceClass="br.com.devmedia.helloworldservice
    .HelloWorldServiceRest"></cxf:rsServer>       
    <bean id="routeBuilder" 
    class="br.com.devmedia.helloworldservice.camel.HelloWorldServiceRouteBuilder" />
	<camelContext xmlns="http://camel.apache.org/schema/spring">
          <routeBuilder ref="routeBuilder" />
    </camelContext>
	
</beans>

Listagem 2. Arquivo de configuraç�o do Spring

Reparem que temos tamb�m o camelContext, respons�vel por gerenciar a execuç�o das rotas. No nosso caso especial, as rotas dizem respeito � implementaç�o do serviço e est�o descritas na classe br.com.devmedia.helloworldservice.camel.HelloWorldServiceRouteBuilder. Veja a listagem 3.


from("cxfrs:bean:server")
.process(new Processor() {

	@Override
	public void process(Exchange exchange) throws Exception {
        Message inMessage = exchange.getIn();                        
        String operationName = inMessage.getHeader(CxfConstants.
        OPERATION_NAME, String.class);
        MessageContentsList list = exchange.getIn().getBody(
        org.apache.cxf.message.MessageContentsList.class);
        org.apache.cxf.message.Message cxfMessage = inMessage.getHeader(
        CxfConstants.CAMEL_CXF_MESSAGE, org.apache.cxf.message.Message.class);
        ServletRequest request = (ServletRequest) cxfMessage.get("HTTP.REQUEST");
        String path = inMessage.getHeader(Exchange.HTTP_PATH, String.class);
        if ("hello".equals(operationName)) {
        	String nome = request.getParameter("nome");
        	if (nome == null) {
                Response r = Response.status(404).
                entity("Nome nao pode ser nulo " + path).build();
                throw new WebApplicationException(r);
        	} else {
	        	exchange.getOut().setBody("Hello " + nome);
        	}
        }
}
});

Listagem 3. Builder para rotas do Camel

A rota inicia-se com from(�cxfrs:bean:server�). Isso quer dizer que estamos consumindo qualquer tipo de dado que vier do bean server, que � o id do cxf:rsServer. Mas n�o estamos, de fato, interessados em qualquer conte�do. Um pouco mais abaixo, obtemos o nome da operaç�o que foi invocada pelo cliente atrav�s do �header� da mensagem encapsulada pelo apache Camel dentro do objeto exchange.

Reparem que para implementarmos a l�gica da operaç�o �hello� da Listagem 1, basta fazermos �if �hello�.equals(operationName)�. A nossa l�gica � bem simples: apenas retornamos �Hello� concatenado ao nome passado por par�metro. Se o nome for nulo, retornamos status 404. O resultado deve ser passado de volta ao camel, atrav�s do exchange.getOut().setBody(..).

Na listagem 4 veremos um exemplo de c�digo de cliente para esse serviço.


WebClient client = WebClient.create(
"http://localhost:8090/hello/helloworldservice");
client.accept("application/json").type("application/json").path("/hello")
.query("nome", "John");
String result = client.get(String.class);
Assert.assertEquals("Hello John", result);

Listagem 4. Cliente para serviço Restful

Na listagem 4 fica claro como � f�cil interagir com esse tipo de serviço. A classe WebClient faz parte do framework apache CXF. Atrav�s dela configuramos o endereço f�sico, o MIME type das mensagens que transmitimos e aceitamos os par�metros (nesse caso �nome�) e obtemos o resultado. Existem outros m�todos interessantes nessa classe que o leitor deve olhar com mais calma.

Esse exemplo simples demonstrou como � f�cil darmos in�cio a um projeto de serviço Restful se usarmos o suporte e os frameworks corretos. Para melhor entendimento do que foi dito sobre REST e RESTFUL, recomendo o excelente livro RESTful Java with JAX-RS escrito pelo grande Bill Burke. � uma verdadeira aula de como construir uma infra-estrutura SOA baseada em ideias relativamente simples.

Servi�os RESTful com Apache CXF e Camel

Veja neste artigo uma abordagem sobre a construção de serviços RESTful utilizando os frameworks Apache CXF e Apache Camel. Veremos também um resumo dos princípios arquiteturais de REST.

Artigos relacionados