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.
Principais Classes
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 |
Consumindo Serviços
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.
Exemplos
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
Implementação
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.