Haciendo mi driver

Preguntas frecuentes

• ¿Cual es la finalidad de un driver?

  La finalidad del driver es actuar de intermediario entre el formato utilizado en su archivo .sav y las aplicaciones que utilizen la librería.

• ¿Cómo la librería sabe que driver usar?

  Todos los archivos .sav compatibles deben tener una cabecera(Header) de 16 bytes codificados en ASCII los cuales sirven de identificador del formato utilizado para en el archivo.

• ¿Qué hace un driver?

  Cuando una aplicación llame a la librería, está leerá la cabecera(Header) del archivo solicitado y identificará que driver debe utilizar y le enviará unicamente el contenido relevante del archivo (El resto del contenido, menos la cabecera) para que este pueda decodificarlo en las clases de las librerías y entregar un arreglo de discos estandarizados para su lectura desde otra aplicación. De esta manera se garantiza que los diversos formatos compatibles con este sistema sean compatibles entre si.

• ¿Qué pasa si tengo algún dato o metadata extra no considerado en las interfaces usadas?

  Para estos casos cada interfaz tiene un campo de Metadata, el cual es un objeto de tipo Map<String, String> donde se puede agregar la información adicional que contempla el formato adaptado.

¿Como hago mi driver?

Para hacer tu driver debes aportar tu código al proyecto, esto significa que debes hacer un aporte al open source, a continuación verás una guía resumida de como hacer esto.

1. Hacer un fork de este repositorio

Hacer un fork básicamente hacer un duplicado del repositorio a tu cuenta de github, esto con el fín de poder editar el código. A continuación te dejamos un tutorial sencillo de como hacerlo. Tutorial de como hacer un fork en github

2. Clonar el repositorio a local

Deberás clonar el repositorio creado a tu computadora para poder hacer las ediciones correspondientes al código fuente. A continuación te dejamos un tutorial sencillo de como hacerlo. Tutorial de como hacer el clon de tu proyecto

3. Crear el driver

Deberás crear una clase dentro del paquete xyz.cupscoffee.files.api.driver.teams Consideraciones (Importante):

• Cada formato de archivo compatible debe contar con una cabecera.
• El nombre de la cabecera debe de ser de 16 caracteres Nota: Si su cabezera ocupa menos de 16 bytes, deberá ser completado con espacio al final para que el Reader pueda leer la cabecera.
• El nombre driver(Clase) debe nombrarse en PascalCase y siguiendo la siguiente estructura: "NombreCabecera" + "Driver"
• El driver debe implementar la interfaz SavDriver
• No se deben crear otras clases adicionales al driver. Nota: En caso lo necesite puede usar clases anidadas.

4. Implementación del driver

En el método readSavFile() debe devolver una instancia de SavFile.

La implementación de este método es propia, acá es donde el driver deberá leer el contenido del archivo y construir el sistema de archivos básico. Debes usar las clases SimpleFile, SimpleFolder, SimpleDisk y SimpleSavStructure para ser instanciadas y posterior mente devueltas por el método. Nota: Cada una de estas clases puede recibir metadata extra en forma de un Map<String, String> la puedes usar en caso requieras guardar metadatos extra de cada uno de las instancias de tu sistema de archivos.

Consideraciones:

• Usar nomenclatura en ingles. Nombres de variables, métodos, etc.
• En caso que necesite lanzar una excepción deberá usar InvalidFormatFileException

5. Probar la solución

1. Deberá probar que su solución funciona antes de enviar sus cambios a su librería. Para esto existen test en la librería donde usted debe agregar un archivo de prueba en su formato dentro del directorio src/test/resources en el proyecto

2. Deberás agregar un test en la clase src/test/java/xyz/cupscoffee/files/api/SavReaderTest.java, de la siguiente forma:

@Test
void testMyProjectDriver() {
  SavStructure actualSavFileStructure = getSavStructure("myproject.sav");

  SavStructure expectedSavFileStructure = DataSupplier.getSavStructure("CupsOfCoffee"); // You cannot change this line
  testSavStructure(expectedSavFileStructure, actualSavFileStructure);
}

Nota: Su driver deberá devolver la misma estructura de archivos que el Driver de prueba. Si tiene dudas, puede consultar la estructura inicial en DataSupplier class

3. Una vez todos los test den luz verde podrá seguir con el paso 6.

6. Aplicar los cambios en la librería

Una vez tenga realizados todos sus cambios en el driver. Deberá aplicar los cambios en la librería. Nota: Recuerde guardar sus cambios en su repositorío fork de la librería, estos cambios no afectarán al código principal de la librería aún.

Para aplicar los cambios deberá realizar abrir una PR para aplicar los cambios desde su fork a la rama principal de la librería.

Ahora a esperar la aprobación por parte de los dueños del repositorio y estar atentos a cualquier comentario sobre su petición o pequeñas correciones.