Configurando Cliente de Web Service HTTPS com Eclipse

Sistema RDR Web Services

Versão 1.0.0 (revisão: 83)

 Banco Central do Brasil, 2010

Sumário
1 Instruções iniciais................................................................................................................3
2 Configuração do Eclipse para geração do cliente WS.......................................................4
2.1 Criando um projeto Básico no Eclipse.........................................................................4
2.2 Verificando a JRE utilizada pelo Eclipse.....................................................................4
2.3 Adicionando Web Services Client no Eclipse SDK.....................................................4
3 Realizando a primeira chamada ao Web Service...............................................................6
3.1 Criando classe com o método main............................................................................6
4 Importando os certificados de acesso................................................................................7
4.1 Baixando os certificados..............................................................................................7
4.2 Importando os certificados para a JVM padrão...........................................................8
5 Respondendo demandas com anexos.............................................................................10
5.1 Operação responder..................................................................................................10
5.2 Operação responderBase64......................................................................................11
6 Recuperando anexos do WS............................................................................................13
7 Problemas conhecidos......................................................................................................14
7.1 Validade do XML........................................................................................................14
7.2 Invalid element org.apache.axis.encoding.ser.BeanDeserializer.onStartChild.........14

 Banco Central do Brasil, 2010

 Configurando Cliente de Web Service HTTPS com Eclipse Página 3 de 14

1 Instruções iniciais
Para esta configuração foi utilizado o Eclipse SDK Helios SR1 com o JRE versão 6
atualização 22 (1.6.0_22-b04) com sistema Windows XP Professional.
Siga a ordem dos tópicos a seguir para concluir a configuração do Cliente.
Se você tem certeza de que nunca importou os certificados do BACEN, necessários
para acesso ao WS, pode ir direto para o passo Importando os certificados de acesso
na página 7, antes de iniciar o passo seguinte, que é a Configuração do Eclipse para
geração do cliente WS.
 Configurando Cliente de Web Service HTTPS com Eclipse Página 4 de 14

2 Configuração do Eclipse para geração do cliente WS

2.1 Criando um projeto Básico no Eclipse

Antes de mapear as classes do web services é necessário criar um projeto Java no
Eclipse.
• Clique em File / New / Java Project;
• Forneça um nome para o projeto (sugestão: clienttest);
• Clique Next;
• Clique em Finish para finalizar a configuração.

2.2 Verificando a JRE utilizada pelo Eclipse

• Clique em Window / Preferences;
• Procure pela aba Java / Installed JREs. Nesta aba aparecerá todas as JVMs
instaladas no sistema. A JRE padrão utilizada pelo Eclipse é a que estiver
marcada.
É possível verificar também por este outro caminho:
• Clique em Help / About Eclipse;
• Agora em Installation Details;
• Clique a aba Configuration;
• procure pelo parâmetro -vm e logo abaixo observe o diretório da VM que o
Eclipse está utilizando (Exemplo: C:\Arquivos de
programas\Java\jre6\bin\client\jvm.dll).
Anote o caminho onde a JRE padrão do Eclipse está instalada, pois será utilizado
mais tarde.

2.3 Adicionando Web Services Client no Eclipse SDK

Para gerar as classes do Web Service:
• Clique em File / New / Other...;
• Procure pelo wizard Web Services / Web Service Client e clique duas vezes
no mesmo;
• No indicador que aparece, arraste o mesmo até o nível Develop client como
mostra a figura abaixo;

• No campo Service definition coloque a URL que possui o WSDL (neste

exemplo use: https://www9.bcb.gov.br/hml/rdrws/services/InstituicaoService?
wsdl);
• Ao terminar de digitar o endereço ou mover o foco para fora do campo, o
Eclipse deverá Exibir uma tela com usuário e senha a serem informados ou a
mensagem de erro The service definition selected is invalid; caso esta
mensagem tenha sido exibida pelo Eclipse, vá para o tópico Importando os
 Configurando Cliente de Web Service HTTPS com Eclipse Página 5 de 14

certificados de acesso (página 7) e ao finalizar este passo adicional, feche o

Eclipse e inicie novamente, retomando a configuração até este ponto.
• Se o certificado tiver sido importado com sucesso, o Eclipse mostrará a tela:

• forneça o User name no formato <instituição><dependência>.<usuário>

(exemplo: 052377975.cef01244) e a senha;
• Clique OK;
• Caso apareça a tela:

• Basta clicar OK e continuar normalmente;

• Na sessão de Configuration: selecione os seguintes itens:
◦ Web service runtime: Apache Axis
◦ Client project: clienttest
observe que o projeto informado deve ser o mesmo projeto criado no passo Criando
um projeto Básico no Eclipse (página 4);
• Clique em Next;
• Clique em Finish e aguarde a criação e geração das classes do Web Service
pelo Eclipse;
 Configurando Cliente de Web Service HTTPS com Eclipse Página 6 de 14

3 Realizando a primeira chamada ao Web Service

Quando a geração das classes estiver finalizada, é necessário adicionar o usuário e
a senha no código gerado pelo Eclipse, antes de criar a classe de teste do Web Service.
• Procure pela classe que possui a terminação BindingStub.java normalmente
ela possui o nome do serviço importado pelo WSDL, exemplo
InstituicaoServiceSoap11BindingStub.java;
• Procure pelo método createCall()
• Procure pelas linhas de código, dentro deste método:
if (super.cachedUsername != null) {
_call.setUsername(super.cachedUsername);
}
if (super.cachedPassword != null) {
_call.setPassword(super.cachedPassword);
}
e altere-as para que fiquem parecidas com:
_call.setUsername("052377975.cef1234");
_call.setPassword("sua senha aqui");

3.1 Criando classe com o método main

Crie uma nova classe no Eclipse dentro do projeto clienttest com o método main
com a seguinte implementação:
public static void main(String[] args) throws Exception {
Calendar dataFim = Calendar.getInstance();
Calendar dataInicio = Calendar.getInstance();
dataInicio.set(Calendar.YEAR, 2009);
String tipoConsulta = "A";
Integer totalDemandas = new
InstituicaoServiceLocator().getInstituicaoServiceHttpSoap11Endpoint().getTotalDe
mandas(dataInicio, dataFim, tipoConsulta, null);
System.out.println(totalDemandas);
}
Execute a classe utilizando a mesma JRE que contém os certificados necessários.
Este código é a consulta do total de demandas existentes para os parâmetros informados,
este total é impresso no console.
Aqui termina a configuração do cliente, lembrando que é apenas uma configuração
de teste e que podem haver particularidades do ambiente que fogem do escopo deste
documento e que devem ser tratadas por conta e risco de quem está implementando.
 Configurando Cliente de Web Service HTTPS com Eclipse Página 7 de 14

4 Importando os certificados de acesso

Para importar os certificados de acesso para a JVM padrão do Eclipse, siga os
passos adiante, lembrando que este procedimento é necessário somente uma vez por
JVM.
Considere que a JVM padrão utilizada pelo Eclipse está instalada em C:\Arquivos de
programas\Java\jre6\.

4.1 Baixando os certificados

• Com o browser Firefox, acesse o endereço do Web Service -
https://www9.bcb.gov.br/hml/rdrws/ ;
• Clique no ícone ao lado esquerdo do endereço do WS

• Clique em Mais informações...;

• Na tela que aparece, clique em Exibir certificado;
• Clique na aba Detalhes;
 Configurando Cliente de Web Service HTTPS com Eclipse Página 8 de 14

• Exporte todos os certificados da Hierarquia clicando sobre o certificado e

logo após no botão Exportar...;
• Salve o certificado no diretório %JAVA_HOME%\lib\security, lembrando que
este JAVA_HOME deve ser a mesma JVM utilizada pelo Eclipse (Exemplo:
C:\Arquivos de programas\Java\jre6\lib\security)
• Se os certificados necessários não tiverem sofrido nenhuma mudança, os
seguintes certificados foram encontrados e baixados para sua máquina:
◦ -.bcb.gov.br.crt
◦ AutoridadeCertificadoradoSERPROFinalv2.crt
◦ AutoridadeCertificadoraRaizBrasileirav1.crt
◦ AutoridadeCertificadoraSERPROv2.crt

4.2 Importando os certificados para a JVM padrão

• Abra o prompt de comando (Iniciar / Executar, cmd, Enter)
• Navegue até o diretório da JVM padrão, digitando o comando cd C:\Arquivos
de programas\Java\jre6\bin;
• Faça um backup copiando o arquivo original C:\Arquivos de
 Configurando Cliente de Web Service HTTPS com Eclipse Página 9 de 14

programas\Java\jre6\lib\security\cacerts para outro lugar, pois este será

modificado ao importar os certificados.
• Supondo que foram baixados os quatro certificados no passo anterior, repita o
comando abaixo quatro vezes, uma para cada certificado, substituindo o
nome em negrito pelo nome do arquivo sem a extensão:
keytool -import -trustcacerts -keystore ../lib/security/cacerts -storepass changeit
-noprompt -alias nome_do_certificado -file ../lib/security/nome_do_certificado.crt

Exemplo:
C:\Arquivos de programas\Java\jre6\bin>keytool -import -trustcacerts
-keystore ../lib/security/cacerts -storepass changeit -noprompt -alias
AutoridadeCertificadoraRaizBrasileirav1 -file
../lib/security/AutoridadeCertificadoraRaizBrasileirav1.crt

C:\Arquivos de programas\Java\jre6\bin>keytool -import -trustcacerts

-keystore ../lib/security/cacerts -storepass changeit -noprompt -alias
AutoridadeCertificadoraSERPROv2 -file
../lib/security/AutoridadeCertificadoraSERPROv2.crt

C:\Arquivos de programas\Java\jre6\bin>keytool -import -trustcacerts

-keystore ../lib/security/cacerts -storepass changeit -noprompt -alias
AutoridadeCertificadoradoSERPROFinalv2 -file
../lib/security/AutoridadeCertificadoradoSERPROFinalv2.crt

C:\Arquivos de programas\Java\jre6\bin>keytool -import -trustcacerts

-keystore ../lib/security/cacerts -storepass changeit -noprompt -alias -.bcb.gov.br
-file ../lib/security/-.bcb.gov.br.crt

Quando o comando for executado corretamente a seguinte mensagem é exibida:

Certificate was added to keystore
Configurando Cliente de Web Service HTTPS com Eclipse Página 10 de 14

5 Respondendo demandas com anexos

O Web Services RDR contempla duas formas de envio de arquivos em resposta a
demandas. Será mostrado a implementação de exemplo das duas estratégias que
possuem complexidade de implementação e performance bem diferentes.
É importante ressaltar essas operações estão disponíveis no serviço
AtualizarDemandaService deste Web Service, o que faz necessário gerar as classes no
Eclipse para este serviço, seguindo os passos descritos na página 4 deste manual
utilizando o endereço correto do serviço de atualização de demandas.

5.1 Operação responder

Envia o arquivo como parte do corpo da requisição HTTP POST no formato MIME
(Multipurpose Internet Mail Extensions).
Essa estratégia de envio de anexo é a mesma que é utilizada para enviar arquivos
em mensagens de e-mail.
Cabe ressaltar que apesar de possuir uma maior complexidade de implementação,
esta operação possui um melhor desempenho em comparação com a Operação
responderBase64 pois o anexo não recebe um tratamento extra para poder ser enviado
além de não ter o tamanho original do arquivo aumentado. É muito importante que esta
operação seja utilizada em detrimento da outra.
A mensagem, no nosso caso o XML, e os anexos, são dispostos em um formato
próprio no corpo da requisição POST, ou seja, o XML e o arquivo são enviados na mesma
requisição, porém ficam separados por delimitadores de conteúdo.
Estes delimitadores de conteúdo possuem informações sobre o tipo, identificador,
versão do conteúdo MIME, entre outros atributos do anexo transportado. (Referências:
http://www.ietf.org/rfc/rfc2045.txt e http://pt.wikipedia.org/wiki/MIME).
Em Java, temos as APIs javax.activation e javax.mail que implementam toda a
complexidade necessária para criar anexos em mensagens com conteúdo MIME.
Antes de codificar o exemplo a seguir é necessário adicionar ao classpath da
aplicação as bibliotecas do JavaMail API. Normalmente possuem o nome activation.jar e
mail.jar e estão inclusas por padrão na maioria dos servidores JEE como JBOSS, Tomcat
e Websphere.
Um dos parâmetros desta operação é o content-id que é o identificador do conteúdo
referente ao anexo que está sendo enviado. A presença deste parâmetro determina se a
resposta a uma demanda está sendo enviada com anexo ou não.
Considerando as classes que foram geradas pelo Eclipse na página 4 deste manual
para o serviço AtualizarDemandaService, é possível encontrar a classe
AtualizarDemandaServiceSoap11BindingStub.
Procure pelo método
br.gov.bcb.rdr.siscapws.services.AtualizarDemandaServiceSoap11BindingStub.responder(
String, Integer, String, String) e adicione as linhas a seguir antes da chamada ao método
setOperationName da instância da classe Call (_call.setOperationName):

File file = new File(nomeArquivo);

nomeArquivo = file.getName();
AttachmentPart attachmentPart = new AttachmentPart(new DataHandler(new
FileDataSource(file)));

contentId = attachmentPart.getContentId();;
_call.addAttachmentPart(attachmentPart);
Configurando Cliente de Web Service HTTPS com Eclipse Página 11 de 14

Observe que nas linhas acima, estamos re-atribuindo as variáveis nomeArquivo e

contentId com os valores reais que serão repassados ao WS durante a chamada.
Logo a seguir tem-se o exemplo da chamada a esta operação, que acionará o WS
enviando o arquivo e a resposta para o encaminhamento:

public class ResponderDemanda {

public static void main(String[] args) throws Exception {
AtualizarDemandaServiceLocator locator = new
AtualizarDemandaServiceLocator();
AtualizarDemandaServicePortType endpoint =
locator.getAtualizarDemandaServiceHttpSoap11Endpoint();
String resposta = "Respondendo o encaminhamento 219603 pelo WS";
Integer idEncaminhamento = new Integer(219603);

String nomeArquivo = "C:\\Pré-projeto.pdf";

endpoint.responder(resposta, idEncaminhamento, null, nomeArquivo);

}
}

5.2 Operação responderBase64

Envia o anexo da resposta codificado em Base 64.
Todo Web Service faz uso do XML como formato de transporte dos dados entre o
cliente e o servidor, porém, o XML possui algumas restrições quanto ao conteúdo que
pode ser colocado; alguns caracteres quando adicionados em um XML torna-o mal
formado e nenhuma ferramenta é capaz de interpretá-lo
(http://www.w3.org/TR/2000/REC-xml-20001006#NT-Char) .
Esta operação recebe o conteúdo do arquivo dentro do corpo do XML enviado ao
Web Service, porém, para que não ocorra erro no processamento do XML, é necessário
converter o conteúdo do arquivo para Base 64 antes de enviar a resposta. Todas as
linguagens de desenvolvimento possuem API nativa para codificação e decodificação de
conteúdo em Base 64, por isso esta técnica é mais fácil de implementar.
A conversão em base 64 resulta em um conteúdo baseado no conjunto de
caracteres ([A-Za-z0-9], "/" e "+") que somam um total de 64 caracteres válidos para um
XML. A codificação Base64 provoca um aumento global de 33% do volume dos dados a
codificar, por isso pode representar uma sensível perda de performance no
processamento (codificação/decodificação) e no tráfego de rede também.
Este trecho de código a seguir é um exemplo de implementação do cliente que envia
a resposta para o Web Service utilizando a operação em questão.
Configurando Cliente de Web Service HTTPS com Eclipse Página 12 de 14

public class ResponderDemandaBase64 {

public static void main(String[] args) throws Exception {
AtualizarDemandaServiceLocator locator = new
AtualizarDemandaServiceLocator();
AtualizarDemandaServicePortType endpoint =
locator.getAtualizarDemandaServiceHttpSoap11Endpoint();
String resposta = "Respondendo o encaminhamento 219216 pelo WS";
Integer idEncaminhamento = new Integer(219216);

File arquivo = new File("C:\\Pré-projeto.pdf");

FileInputStream arquivoIS = new FileInputStream(arquivo);
ByteArrayOutputStream saida = new ByteArrayOutputStream();
copia(saida, arquivoIS);

byte[] conteudoStringArquivo = saida.toByteArray();

String nomeArquivo = arquivo.getName();

String contentType = arquivo.toURL().openConnection().getContentType();
String conteudoBase64 = Base64.encode(conteudoStringArquivo);
if("content/unknown".equals(contentType)){
contentType = "application/octet-stream";
}

endpoint.responderBase64(resposta, idEncaminhamento, nomeArquivo,

contentType, conteudoBase64);
}
/**
* copiar uma stream para outra
* @param destino
* @param origem
* @throws IOException
*/
public static void copia(OutputStream destino, InputStream origem)throws
IOException {
byte[] buffer = new byte[8192];
int qtdeLida = 0;

while ((qtdeLida = origem.read(buffer)) > 0) {

destino.write(buffer, 0, qtdeLida);
}

destino.close();
origem.close();
}
}
Configurando Cliente de Web Service HTTPS com Eclipse Página 13 de 14

6 Recuperando anexos do WS
Considerando uma plataforma em Java, os anexos de cada demanda podem ser
recuperados através do componente Commons HTTP Client e Commons Codec da
Apache. Logo abaixo, tem-se um exemplo de como recuperar um anexo utilizando estes
componentes.
O exemplo abaixo utilizou o commons-httpclient versão 3.1 e o commons-codec 1.3.
Lembrando que para conectar-se com sucesso ao servidor é necessário importar os
certificados de acesso para a JVM a ser utilizada (página 7).

public class AnexosDownload {

public static void main(String[] args) throws Exception {
HttpClient client = new HttpClient();

//Autenticação do WS, aqui deve ser informado o usuário e a senha para

acesso ao SISBACEN.
client.getState().setCredentials(new AuthScope("www9.bcb.gov.br", 443,
"SISBACEN"), new UsernamePasswordCredentials("usuário sisbacen", "senha"));

//essa URL é montada pelo WS, aqui é apenas um exemplo de url onde o
anexo está disponível
GetMethod get = new GetMethod("https://www9.bcb.gov.br/hml/rdrws/anexos?
id=279083");
get.setDoAuthentication(true);
client.executeMethod(get);

//Nome do arquivo
String nomeArquivo = get.getResponseHeaders("Content-Disposition")
[0].getElements()[0].getParameterByName("filename").getValue();

//Conteúdo do arquivo
InputStream arquivo = get.getResponseBodyAsStream();

get.releaseConnection();

}
}
Configurando Cliente de Web Service HTTPS com Eclipse Página 14 de 14

7 Problemas conhecidos
Configurando o Web Services client com este tutorial foram detectados alguns
problemas que podem ocorrer ao realizar as chamadas. Alguns destes problemas são
descritos aqui.

7.1 Validade do XML

Web Services utilizam XML como formato de intercomunicação de dados, porém, é
importante observar que o conteúdo texto deve obedecer os caracteres permitidos para
que não ocorra erro no processamento do XML. Os caracteres válidos para um XML estão
descritos na especificação da W3C - http://www.w3.org/TR/2000/REC-xml-20001006#NT-
Char .

7.2 Invalid element

org.apache.axis.encoding.ser.BeanDeserializer.onStartChild
Existe um bug cadastrado para este erro em
https://issues.apache.org/jira/browse/AXIS-2758 , mas como o AXIS 1.4 não é mais
evoluído, não existe versão com o BUG corrigido. A versão 2 é a mais recente do
framework AXIS, mas a forma de configuração e arquitetura são totalmente diferentes da
versão utilizada neste manual, que é a primeira.
Para correção do erro é necessário alterar uma das classes geradas pelo Eclipse.
• Procure pela classe com terminação BindingStub;
• Esta classe possui um método de inicialização das definições dos serviços -
_initOperationDesc1;
• Na implementação deste método, procure pela inicialização de operações do
WS que retornem uma coleção de objetos;
• Altere a chamada ao método void
org.apache.axis.description.OperationDesc.setReturnClass(Class
returnClass) colocando a classe simples, e não o array da classe, como o
Eclipse gerou inicialmente;
Antes:
oper.setReturnClass(br.gov.bcb.rdr.siscapws.objetos.xsd.DemandaOUT[].class);

Depois:
oper.setReturnClass(br.gov.bcb.rdr.siscapws.objetos.xsd.DemandaOUT.class);