API para integração do SIGED com outros sistemas

O SIGED conta com uma API para que outros sistemas possam realizar consultas e manipulações de documentos na sua base de dados. Essa API foi feita com o objetivo de ser acessada via Spring HTTP Invoker ou via Web Service (ainda não implementado), dependendo da localização do sistema cliente.

A seguir, serão listadas as principais classes, como Data Transfer Objects e Interfaces Remotas, que serão utilizadas na integração de outros sistemas com o SIGED. Essas classes encontram-se no pacote br.ufrn.integracao.siged, no projeto da arquitetura.

A classe DescritorDTO tem como objetivo armazenar as principais informações de um descritor para que elas possam ser utilizadas em outros sistemas. Dessa forma, os sistemas têm acesso apenas às informações que realmente serão necessárias para o seu funcionamento, obedecendo assim ao princípio do encapsulamento, e não haverá acoplamento entre eles e o SIGED. A classe DescritorDTO pode armazenar ainda a informação do valor de um descritor para um determinado documento, o que a torna, portanto, equivalente às classes Descritor e ValorDescritor do SIGED.

Os seus atributos são:

De forma equivalente à classe DescritorDTO, essa classe tem como objetivo armazenar as principais informações de um documento para que elas possam ser utilizadas em outros sistemas. A classe DocumentoDTO é equivalente à classe Documento do SIGED.

Os seus atributos são:

A classe PastaDocumentoDTO tem como objetivo armazenar as principais informações de uma pasta de documentos para que elas possam ser utilizadas em outros sistemas.

Os seus atributos são:

Em Casos de Uso envolvendo documentos funcionais, iniciados à partir do SIGPRH e utilizando a comunicação com o serviço remoto do SIGED, utilizar o seguinte padrão para a criação das pastas:

DOCUMENTOS FUNCIONAIS\SIAPE-NOME\CASO DE USO

por exemplo:

DOCUMENTOS FUNCIONAIS\312654-JOAO SILVA\CAPACITAÇÕES

DOCUMENTOS FUNCIONAIS\312654-JOAO SILVA\COMPROVANTE AUXILIO TRANSPORTE

onde DOCUMENTOS FUNCIONAIS é o diretório raíz de todos os documentos funcionais dos servidores, o id deste diretório está mapeada na tabela comum.parametros com o parâmetro DIRETORIO_DOCUMENTOS_FUNCIONAIS_SIGED. O diretório 312654-JOAO SILVA deverá ser uma instância de PastaDocumentoDTO, e “CERTIFICADOS CAPACITAÇÕES”, “COMPROVANTE AUXILIO TRANSPORTE” deverão ser também instâncias de PastaDocumentoDTO com a propriedade “pai” apontando para o id da PastaDocumento “312654-JOAO SILVA” (sendo portanto, pela abstração do SIGED, suas sub-pastas).

Data Transfer Object com as principais informações retornadas pela busca de documentos do SIGED. Cada objeto ResultadoBuscaDTO está associado a um objeto DocumentoDTO, trazendo ainda algumas informações adicionais, como a relevância da busca e o texto no documento que casou com a busca. A classe ResultadoBuscaDTO é equivalente à classe ResultadoBusca, do SIGED.

Os seus atributos são:

Interface que define as principais informações de um arquivo, para que ele possa ser inserido na base de arquivos através da classe EnvioArquivoHelper. A classe existe para que a API seja agnóstica com relação à forma de envio de arquivos utilizada pelo sistema cliente. Para que o sistema cliente adapte a sua forma de envio de arquivos para a API do SIGED, basta que seja criado um adapter com esse fim. A próxima classe é um exemplo disso.

Métodos da Interface:

Para envio de arquivos, é comum utilizarmos os componentes do Tomahawk, da Apache. O envio de arquivos do Tomahawk expõe os dados do arquivo através da interface UploadedFile. Essa classe adapta a interface do UploadedFile para a interface ArquivoDocumento, da API de integração do SIGED. Para utilizá-la, basta instanciar um UploadedFileAdapter passando como parâmetro do construtor um UploadedFile.

A implementação do adapter, para servir de exemplo para implementação de outros adapters, está listada abaixo:

public class UploadedFileAdapter implements ArquivoDocumento {
 
   private UploadedFile file;
 
   public UploadedFileAdapter(UploadedFile file) {
      this.file = file;
   }
 
   public byte[] getBytes() throws IOException {
      return file.getBytes();
   }
 
   public String getContentType() {
      return file.getContentType();
   }
 
   public String getName() {
      return file.getName();
   }
 
   public long getSize() {
      return file.getSize();
   }
 
}

E o seu uso pode ser visto abaixo:

UploadedFile uploadedFile = ...;
ArquivoDocumento arquivo = new UploadedFileAdapter(uploadedFile);

Classe contendo constantes com os identificadores dos principais tipos de documento.

Essa interface é o principal mecanismo de integração com o SIGED. Contém os métodos que irão possibilitar a interação entre os sistemas, permitindo busca, cadastro, atualização, remoção, etc. de documentos. Os sistemas têm acesso apenas à interface. A implementação da interface está no SIGED e os sistemas a acessam através do Spring Http Invoker ou através de Web Services. Nas seções a seguir será mostrado com maior detalhes como utilizar essa interface.

Os métodos disponíveis atualmente são os seguintes:

Para consumir os serviços da API de integração do SIGED, deve-se declarar bean integracaoSigedInvoker no remote-services.xml do sistema para o qual se está fazendo a integração, conforme documentado na seção de integração entre sistemas.

<bean id="integracaoSigedInvoker" class="br.ufrn.integracao.siged.SigedHttpInvokerProxyFactoryBean">
   <property name="serviceUrl" value="${sigedRemoteHost}/remoting/IntegracaoSigedService"/>
   <property name="serviceInterface" value="br.ufrn.integracao.siged.IntegracaoSigedService"/>
</bean>

Para o uso em um managed bean do JSF, deve-se injetar o bean em um atributo do tipo IntegracaoSigedService utilizando a anotação @Autowired. Depois basta utilizar normalmente os métodos da interface.

@Component @Scope("request")
public class ExemploIntegracaoSigedMBean extends AbstractController {
 
   @Resource(name="integracaoSigedInvoker")
   private IntegracaoSigedService siged;
 
   public String buscarDocumento() {
      DocumentoDTO doc = siged.buscarPorId(10);
     /* ... */
   }
 
}

Para uma action do Struts, deve-se utilizar o método getBean(), definido em AbstractAction, passando como parâmetros request e o nome do bean: “integracaoSigedInvoker”.

public class ExemploIntegracaoSigedAction extends AbstractAction {
 
   public ActionForward execute(ActionMapping mapping, ActionForm form, HttpServletRequest req,
			HttpServletResponse res) throws Exception {
 
      IntegracaoSigedService siged = getBean(req, "integracaoSigedInvoker");
      DocumentoDTO doc = siged.buscarPorId(10);
      /* ... */
 
   }
 
}

Nos processadores, deve-se utilizar o método getBean(), definido em AbstractProcessador, passando como parâmetros o nome do bean: “integracaoSigedInvoker” e o movimento.

public class ProcessadorExemploIntegracaoSiged extends AbstractProcessador {
 
   public Object execute(Movimento mov) throws NegocioException, ArqException, RemoteException {
 
      IntegracaoSigedService siged = getBean("integracaoSigedInvoker", mov);
      DocumentoDTO doc = siged.buscarPorId(10);
      /* ... */
 
   }
 
}

Ainda não implementado. Sem previsão de implementação por enquanto.

Para os exemplos a seguir, deve-se considerar que o objeto siged já foi corretamente buscado de acordo com a seção anterior.

Código:

List<DescritorDTO> descritores = siged.buscarDescritores(10);
for (DescritorDTO descritor : descritores) {
   System.out.println(descritor.getId() + " - " + descritor.getDescricao() + " - " + descritor.getTipoDocumento());
}

Saída:

17 - Titulo - 10
18 - Autores - 10

Código:

DocumentoDTO documento = siged.buscarPorId(getUsuarioLogado(), 66);
System.out.println(documento.getId());
System.out.println(documento.getIdArquivo());
System.out.println(documento.isIndexavel());
System.out.println(documento.getLocalizacaoFisica());
System.out.println(documento.getPalavrasChaves());
System.out.println(documento.getTipoDocumento());
System.out.println(documento.getLocalizacao());
for (DescritorDTO descritor : documento.getDescritores()) {
   System.out.println(descritor.getId() + " - " + descritor.getDescricao() + " - " + descritor.getTipoDocumento());
}

Saída:

66
2984
true
l
k
10
null
3918654 - Autores - 10
3918655 - Título - 10

A partir deste momento, vamos considerar que o código usado acima para imprimir as informações do documento está no método void imprimirDocumento(DocumentoDTO documento).

Código:

List<ResultadoBuscaDTO> resultado = siged.buscarDocumentos(getUsuarioLogado(), "software");
for (ResultadoBuscaDTO item : resultado) {
   imprimirDocumento(item.getDocumento());
   System.out.println("Texto: " + item.getTexto());
   System.out.println("______");
}

Saída:

58
2317
10
46
3917883 - Autores - 10
3917884 - Título - 10
Texto:  Hibernate [3], allows <span class="liusHit">software</span>
developers to.... In a scenario described above, ORM <span class="liusHit">software</span>... designed to 
replace ORM in <span class="liusHit">software</span>... targets <span class="liusHit">software</span> working 
with semi-structured... Data Model RDBMS <span class="liusHit">software</span> application ORM
______
56
2302
10
50
3917864 - Autores - 10
3917865 - Título - 10
Texto:  de experiência em desenvolvimento de <span class="liusHit">software</span>. Trabalha há 7 anos em fábricas de 
<span class="liusHit">software</span> e projetos.... Gestores de fábricas de <span class="liusHit">software</span> 
procuram... traduzir requisitos em componentes do <span class="liusHit">software</span>... de 
<span class="liusHit">software</span> não deve ter ambigüidades e 

e diversos outros resultados...

Código:

DocumentoDTO doc = new DocumentoDTO();
doc.setTipoDocumento(10);
doc.setIndexavel(true);
doc.setLocalizacaoFisica("testando localizacao");
doc.setPalavrasChaves("testando palavras chave");
 
List<DescritorDTO> descritores = siged.buscarDescritores(10);
for (DescritorDTO descritor : descritores) {
   descritor.setValor("teste descritor " + descritor.getDescricao());
}
doc.setDescritores(descritores);
doc = siged.cadastrarDocumento(doc, new UploadedFileAdapter(arquivo), getUsuarioLogado());
 
DocumentoDTO cadastrado = siged.buscarPorId(getUsuarioLogado(), doc.getId());
imprimirDocumento(cadastrado);

Saída:

69
3134
testando indexador
testando localizacao
testando palavras chave
10
null
3918673 - Autores - 10
3918674 - Título - 10

A implementação da API de integração do SIGED está no pacote br.ufrn.siged.remote, do projeto SIGED. É formada basicamente por duas classes: IntegracaoSigedServiceImpl e SigedUtils. A classe IntegracaoSigedServiceImpl contém a implementação dos métodos da interface e é essa classe que é chamada pelos demais sistemas quando utilizam a integração com o SIGED.

Ela pode ser exposta via Web Services ou via o Spring Http Invoker. No momento, apenas o Http Invoker está sendo utilizado. Para expô-la com o Http Invoker, foi declarado o bean integracaoSigedExporter no remote-services.xml, conforme o código abaixo:

<bean name="integracaoSigedExporter" class="org.springframework.remoting.httpinvoker.HttpInvokerServiceExporter">
   <property name="service" ref="integracaoSigedServiceImpl"/>
   <property name="serviceInterface" value="br.ufrn.integracao.siged.IntegracaoSigedService"/>
</bean>

Além disso, foi necessário declarar um Servlet no SIGED para que os demais sistemas acessem. O nome do servlet deve ser igual ao nome do bean declarado anteriormente: integracaoSigedExporter.

<servlet>
  <servlet-name>integracaoSigedExporter</servlet-name>
  <servlet-class>org.springframework.web.context.support.HttpRequestHandlerServlet</servlet-class>
</servlet>
 
<servlet-mapping>
  <servlet-name>integracaoSigedExporter</servlet-name>
  <url-pattern>/remoting/IntegracaoSigedService</url-pattern>
</servlet-mapping>

A outra classe é a SigedUtils, que contém métodos para transformar as classes do SIGED nos DTOs equivalentes e os DTOs nas classes.