====== Mapear BFILES con Hibernate ======
En esta wiki se va a describir cómo mapear tipos de datos **BFILE** de Oracle para trabajar directamente con ficheros en Hibernate/JPA.


Un **BFILE** no es un fichero, es un **puntero a un fichero** que se encuentra en un directorio gestionado por Oracle.


===== Guía detallada =====

Ficheros que intervienen en el mapeo:

  * **FundeWebOracle10gDialect**: Dialect para registrar los types de Oracle. __Librería fundeweb-hibernate a partir de las versiones: [1.5.107 , 2.0.13,  2.0.111]__.
  * **BFileToByteArrayType**: type para trabajar directamente con byte[] en la entidad.
  * **BFileType**: type para trabajar con OracleBfile en la entidad. 
  * **PreventRemove**: Listener básico para prevenir que no se borren los registros de la entidad (si se borra un bfile/puntero puede dejar un fichero huérfano en los directorios de la bbdd).  __Librería fundeweb-jpa a partir de las versiones: [1.5.113 , 2.0.18,  2.0.103].__


===== Configuración y uso =====

<WRAP center round important 60%>
De momento esta configuración solo es válida para la **LECTURA** de BFILEs.
</WRAP>

\\
=== 1. Fichero persistence.xml ===
\\
Sustituir la propiedad **hibernate.dialect** por: 

<code xml>
<property name="hibernate.dialect" value="es.um.atica.hibernate.dialect.FundeWebOracle10gDialect"/>
</code>
\\
=== 2. Entidad ===
- Anotar la entidad que contiene la columna BFILE con: 
 <code java> 
 @EntityListeners( PreventRemove.class )
 </code>
\\
<WRAP center round info 60%>
Elegir una de las siguientes opciones para mapear el BFILE en la entidad.
</WRAP>

-  __**[OPCIÓN A]** Si el formato de los ficheros a recuperar es **conocido y siempre es el mismo**__:
  * Declarar la columna del BFILE como **byte[]**
<code java>private byte[] fichero;</code>
  * Anotar el **get** de la columna con:
<code java>
  @Column( name = "[NOMBRE_COLUMNA]", updatable = false, insertable = false )
  @Type( type = "es.um.atica.hibernate.type.BFileToByteArrayType" )
  public byte[] getFichero() {
	return fichero;
  }
</code>
\\
- __**[OPCIÓN B]** Si el formato de los ficheros a recuperar **no es conocido o puede variar**__:
  * Declarar la columna como **oracle.jdbc.OracleBfile**
<code java>private OracleBfile fichero;</code>
  * Anotar el **get** de la columna con:
<code java>
  @Column( name = "[NOMBRE_COLUMNA]", updatable = false, insertable = false )
  @Type( type = "es.um.atica.hibernate.type.BFileType" )
  public OracleBfile getFichero() {
	return fichero;
  }
  </code>
  * Crear un método //Transient// para obtener el byte[]:
<code java>
       //Ejemplo con columna 'fichero'
	@Transient
	public byte[] getFicheroBytes() throws SQLException {

		byte[] result = null;
		
		try {
			if ( this.fichero != null && this.fichero.fileExists() ) {
				this.fichero.openFile();
				java.io.ByteArrayOutputStream bao = new java.io.ByteArrayOutputStream();
				java.io.InputStream in = this.fichero.getBinaryStream();
				byte[] buffer = new byte[1024];
				int len = -1;
				while ( ( len = in.read( buffer, 0, buffer.length ) ) > -1 ) {
					bao.write( buffer, 0, len );
					bao.flush();
				}
				bao.close();
				result = bao.toByteArray();
				this.fichero.closeFile();
			}
		} catch ( Exception ex ) {
			throw new SQLException( "Could not read OracleBfile:", ex );
		}

		return result;
	}
</code>
  * Crear un método //Transient// para obtener el nombre del fichero:
<code java>
        //Ejemplo con columna 'fichero'
        @Transient
	public String getFicheroName() throws SQLException {

		String result = null;

		if ( this.fichero != null && this.fichero.fileExists() ) {
			result = this.fichero.getName();
		}

		return result;
	}
</code>
\\


=== 3. Manejador ===

__Ejemplo con columna byte[] en FundeWeb 2.0 (OPCIÓN A)__

<code java>
//ejemplo simplificado con entidad 'f' y columna 'fichero' 
InputStream stream = new ByteArrayInputStream( f.getFichero() ); 
StreamedContent fileDownload = new DefaultStreamedContent( stream, "application/pdf", "miFichero.pdf");
</code>

\\
__Ejemplo con columna OracleBfile en FundeWeb 2.0 (OPCIÓN B)__

<code java>
//ejemplo simplificado con entidad 'f' y columna 'fichero'
InputStream stream = new ByteArrayInputStream( f.getFicheroBytes() ); 
String mimeType = java.net.URLConnection.guessContentTypeFromName( f.getFicheroName() );
      
StreamedContent fileDownload = new DefaultStreamedContent( stream, mimeType, f.getFicheroName() );
</code>
\\

<WRAP center round info 60%>
Como se puede observar, la configuración de la OPCIÓN A es más simple. \\
Como contrapartida, tendremos que gestionar desde el manejador el nombre y el mimetype del fichero a descargar. \\
Esta configuración es **OPCIONAL** cuando el tipo de archivo apuntado es **fijo y conocido**.
\\
\\
La configuración de la OPCIÓN B, no es tan directa como la anterior, 
pero permite recuperar desde base de datos tanto el nombre como la extensión del fichero apuntado por el BFILE.\\
Esta configuración es **OBLIGATORIA** cuando el tipo de archivo apuntado **puede variar**.\\
Esta configuración es **OPCIONAL** cuando el tipo de archivo apuntado es **fijo y conocido**.

Se deja a criterio del programador usar una opción de mapeo u otra.
</WRAP>

=== 4. Permisos a los directorios ===
Para poder acceder a los ficheros desde los diferentes entornos de nuestra aplicación habrá que solicitar, via **JIRA** a **SISTEMAS** (proyecto **BD - DJ-AT-SIST-BD**), \\ permisos de **lectura** para el usuario **JV_** de nuestra aplicación a los **directorios apuntados por los BFILEs**.\\

Pueden encontrarse los directorios apuntados haciendo una consulta a la tabla que contiene el BFILE. \\
El BFILE aparecerá con formato: <code>bfilename('DIRECTORIO','NOMBRE_FICHERO')</code>.
\\ 
Ante cualquier duda al respecto, poneos en contacto con MNCS.

===== Referencias =====

[[https://wiki.um.es/wikis/programador/doku.php?id=plsql:pl_sql#lobs_tips | LOBs tips]]

[[https://wiki.um.es/wikis/programador/doku.php?id=plsql:blob_a_bfile&s[]=bfile | PASO DE BLOBs A BFILEs.]]

[[https://wiki.um.es/wikis/programador/doku.php?id=plsql:bfile_fundeweb&s[]=bfile | Trabajo con bfile]]

----
 --- //[[ramon.ginel@ticarum.es|RAMON GINEL GEA]] 01/02/2021 13:19//