Referencia de la API

📚 Referencia de la API

Esta página proporciona una visión técnica detallada de los paquetes, clases clave, enumeraciones y el sistema de excepciones que componen qrgenerator. Utiliza esta guía para entender los componentes internos y extender la librería si es necesario.

---

📦 Estructura de Paquetes

La librería está organizada en cuatro paquetes principales, manteniendo un desacoplamiento estricto entre el dominio, la configuración y la infraestructura de renderizado:

Paquete	Descripción	Componentes Clave
co.com.japl.dev.qr.generator.core	Núcleo de la librería y puntos de entrada principales.	QRGenerator, QRResult
co.com.japl.dev.qr.generator.spec	Modelos de configuración, contratos de diseño y enums estéticos.	QRSpecification, ModuleShape, EyeShape
co.com.nano871022.qr.generator.render	Infraestructura de dibujo encargada de transformar la matriz lógica en gráficos.	RenderEngine, MatrixRenderer
co.com.japl.dev.qr.generator.exception	Jerarquía de excepciones personalizadas de la librería.	QRGeneratorException, RenderException

---

🛠️ Clases e Interfaces Clave

QRGenerator

Es la fachada principal (Facade) de la librería. Contiene los métodos estáticos para iniciar el proceso de generación.

• public static QRResult generate(String content, QRSpecification spec)
  • Propósito: Punto de entrada para calcular la matriz del QR y preparar el motor de renderizado.
  • Lanza: InvalidDataException si el contenido está vacío o excede la capacidad del nivel de redundancia; RenderException si ocurre un fallo al procesar elementos visuales.

QRSpecification

Clase inmutable que almacena las reglas de diseño. Solo se puede instanciar utilizando su clase interna estática QRSpecification.Builder.

• Métodos del Builder más comunes:
  • withSize(int width, int height): Define las dimensiones en píxeles.
  • withBackgroundColor(Color color): Define el color del fondo.
  • withForegroundColor(Color color): Define el color de los módulos de datos.
  • withModuleShape(ModuleShape shape): Asigna la geometría de los puntos de datos.
  • withEyeShape(EyeShape shape): Asigna la geometría de las tres esquinas de control.
  • withLogo(BufferedImage logo): Incrusta una imagen central.
  • withLogoScale(float scale): Escala relativa del logo (rango recomendado: 0.15f a 0.22f).

QRResult

Es el objeto contenedor retornado por QRGenerator. Proporciona métodos fluidos para exportar el gráfico generado a diferentes destinos.

• public void toFile(File targetFile): Guarda la imagen directamente en el sistema de archivos.
• public void toStream(OutputStream outputStream): Escribe los bytes de la imagen en un flujo (ideal para controladores web).
• public BufferedImage toBufferedImage(): Retorna el objeto en memoria para su manipulación directa.

---

🎛️ Enumeraciones (Enums)

ErrorCorrectionLevel

Determina la capacidad de recuperación de datos del código QR si se daña o se obstruye con un logo central.

Valor	Capacidad de Recuperación	Caso de Uso Recomendado
LOW	~7% de los datos destruidos.	QRs limpios, de alta densidad de datos y sin logos.
MEDIUM	~15% de los datos destruidos.	Configuración estándar por defecto.
QUARTILE	~25% de los datos destruidos.	QRs comerciales con logos pequeños.
HIGH	~30% de los datos destruidos.	Obligatorio si usas logos grandes o colores complejos.

ModuleShape

Define la geometría de los módulos individuales de datos (los "píxeles" del QR).

• SQUARE: El clásico píxel cuadrado tradicional (máxima compatibilidad).
• ROUNDED: Cuadrados con esquinas suavizadas para un aspecto más limpio.
• DOTS: Transforma cada módulo de datos en un círculo independiente.

EyeShape

Define la apariencia estética de los tres patrones de detección de posición grandes ubicados en las esquinas superiores e inferior izquierda.

• SQUARE: Diseño clásico cuadrado y rígido.
• CIRCLE: Ojos completamente circulares (estilo futurista).
• ROUNDED_RECTANGLE: Esquinas externas e internas suavizadas.

---

🚨 Manejo de Errores (Excepciones)

Todas las excepciones lanzadas de manera controlada por la librería heredan de una excepción base de tipo RuntimeException, lo que evita la obligación de capturarlas explícitamente si prefieres delegarlas a un manejador global (como @ControllerAdvice en Spring Boot).

[ RuntimeException ] │ ▼ [ QRGeneratorException ] (Base) ├──► [ InvalidDataException ] └──► [ RenderException ]

• QRGeneratorException: Excepción base del proyecto.
• InvalidDataException: Se lanza de forma temprana si el texto de entrada es nulo, vacío, o si el volumen de caracteres supera el límite físico del estándar QR para el nivel de corrección seleccionado.
• RenderException: Se lanza durante la fase de dibujo si los componentes de java.awt fallan, si el archivo de salida no tiene permisos de escritura, o si la escala del logo de entrada corrompe los límites de seguridad de la matriz.