====== 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 [[desenvolvimento:especificacoes:siged:casos_de_uso:administracao:cadastros:descritores|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 [[desenvolvimento:especificacoes:siged:estudo:proposta_ged_ufrn|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:

<code>DOCUMENTOS FUNCIONAIS\SIAPE-NOME\CASO DE USO</code>

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 [[desenvolvimento:especificacoes:arquitetura:servicos:arquivos:envio_arquivos|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 [[http://en.wikipedia.org/wiki/Adapter_pattern|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:

<code java>
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();
   }
	
}
</code>

E o seu uso pode ser visto abaixo:

<code java>
UploadedFile uploadedFile = ...;
ArquivoDocumento arquivo = new UploadedFileAdapter(uploadedFile);
</code>

==== 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 [[desenvolvimento:especificacoes:arquitetura:servicos:integracao_entre_sistemas|integração entre sistemas]].

<code xml>
<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>
</code>

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.

<code java>
@Component @Scope("request")
public class ExemploIntegracaoSigedMBean extends AbstractController {

   @Resource(name="integracaoSigedInvoker")
   private IntegracaoSigedService siged;

   public String buscarDocumento() {
      DocumentoDTO doc = siged.buscarPorId(10);
     /* ... */
   }

}
</code>

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

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

   }

}
</code>

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

<code java>
public class ProcessadorExemploIntegracaoSiged extends AbstractProcessador {

   public Object execute(Movimento mov) throws NegocioException, ArqException, RemoteException {

      IntegracaoSigedService siged = getBean("integracaoSigedInvoker", mov);
      DocumentoDTO doc = siged.buscarPorId(10);
      /* ... */

   }

}
</code>

==== 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:**//

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

//**Saída:**//

  17 - Titulo - 10
  18 - Autores - 10
==== Buscar documento por ID ====

//**Código:**//

<code java>
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());
}
</code>

//**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:**//

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

//**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:**//

<code java>
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);
</code>

//**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:

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

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

<code xml>
<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>
</code>

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