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.

DescritorDTO

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:

Atributo Significado
id Identificador do Descritor no SIGED.
descricao Nome do descritor.
tipoDocumento Tipo de documento do qual o descritor faz parte.
documento Documento associado ao descritor, para quando esta classe for usada como equivalente da classe ValorDescritor do SIGED. Pode ser nulo.
valor Valor do descritor quando associado a um documento. Pode ser nulo.

DocumentoDTO

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:

Atributo Significado
id Identificador do documento no SIGED.
tipoDocumento Identificador do tipo do documento.
idArquivo Id do arquivo (na base de arquivos) associado ao documento.
indexavel Identifica se o documento é indexável ou não. É um boolean.
palavrasChave Palavras-chave do documento. É uma String.
localizacaoFisica Localização física do documento. É uma String.
descritores Uma lista de objetos do tipo DescritorDTO, que contém os descritores do documento e seus valores.
localizacao Identificador da pasta em que o documento será armazenado. Pode ser null, se for armazenar na raiz.

PastaDocumentoDTO

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:

Atributo Significado
id Identificador da pasta no SIGED.
nome Nome da pasta.
pai Pasta na qual essa pasta está inserida. Null, se a pasta estiver na raiz.

Utilização no SIGRH

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).

ResultadoBuscaDTO

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:

Atributo Significado
documento DTO do Documento retornado pela busca.
texto Texto que casa com a string de busca.
relevancia Relevância do resultado na busca.

ArquivoDocumento

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:

Método Significado
byte[] getBytes() Retorna o conteúdo do arquivo como um array de bytes.
String getContentType() String que identifica o tipo do conteúdo do arquivo.
String getName() Retorna o nome do arquivo.
long getSize() Retorna o tamanho do arquivo em bytes.

UploadedFileAdapter

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);

TiposDocumento

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

IntegracaoSigedService

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:

Método Significado
List<DescritorDTO> buscarDescritores(int tipoDocumento) Busca os descritores associados a um determinado tipo de documento.
DocumentoDTO cadastrarDocumento(DocumentoDTO documento, ArquivoDocumento arquivo, infoUsuarioDTO usuario) Cadastra um documento no SIGED. Deve-se passar como parâmetro o documento a ser cadastrado, o arquivo associado ao documento e o usuário que está cadastrando. Caso o usuário não tenha permissão para cadastrar o documento em questão, será disparada uma exceção.
PastaDocumentoDTO cadastrarPastas(InfoUsuarioDTO usuario, String diretorio, Integer idPastaPai) Cadastra uma árvore de pastas no SIGED.
DocumentoDTO cadastrarPastasDocumento(DocumentoDTO documento, ArquivoDocumento arquivo, InfoUsuarioDTO usuario, String diretorio, Integer idPastaPai) Cadastra um documento e sua árvore de pastas no SIGED.
DocumentoDTO atualizarDocumento(DocumentoDTO documento, ArquivoDocumento arquivo, infoUsuarioDTO usuario) Atualiza um documento no SIGED. Deve-se passar como parâmetro o documento a ser atualizado, o arquivo associado ao documento e o usuário que está cadastrando. Se o arquivo for null, mantém o que está. Se for diferente de null, atualiza o arquivo.
void excluirDocumento(infoUsuarioDTO usuario, int idDocumento) Exclui um documento do SIGED de acordo com o id passado como parâmetro.
PastaDocumentoDTO buscarPasta(String nome, Integer pai) Dado um nome e a pasta pai, retorna a pasta de documentos que possui esses valores no SIGED.
PastaDocumentoDTO cadastrarPasta(PastaDocumentoDTO pasta, infoUsuarioDTO usuario) Cadastra uma pasta de documentos no SIGED. Deve-se passar como parâmetro as informações da pasta e o usuário que está cadastrando.
DocumentoDTO buscarPorId(infoUsuarioDTO usuario, int id) Dado o ID de um documento, retorna um DocumentoDTO com as suas principais informações.
DocumentoDTO buscarPorIdArquivo(infoUsuarioDTO usuario, int idArquivo) Busca um documento pelo identificador do arquivo associado ao mesmo.
List<ResultadoBuscaDTO> buscarDocumentos(infoUsuarioDTO usuario, String criterio) Método para busca de documentos por um critério. Busca dados no conteúdo dos documentos.
List<ResultadoBuscaDTO> buscaAvancada(infoUsuarioDTO usuario, Integer tipoDocumento, List<DescritorDTO> descritores, String criterio) Método para busca avançada de documentos, podendo restringir a busca por tipo de documento, valores de descritores e um determinado texto no seu conteúdo.
void excluirDocumento(infoUsuarioDTO usuario, int idDocumento) Exclui um documento do SIGED de acordo com o ID do documento passado por parâmetro
void excluirDocumentoPorIdArquivo(infoUsuarioDTO usuario, int idArquivo) Exclui um documento do SIGED de acordo com o ID do arquivo associado ao documento

HTTP Invoker

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);
      /* ... */
 
   }
 
}

Web Services

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.

Busca de Descritores

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

Buscar documento por ID

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).

Busca de Documentos

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...

Cadastro de Documentos

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.

  • desenvolvimento/especificacoes/siged/api_integracao.txt
  • Última modificação: 2017/04/03 18:15
  • (edição externa)