From 66f0c20276df6dd5e9f529dac0e534eae095d13a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Daniel=20Cort=C3=A9s?= Date: Sun, 7 Jul 2019 17:34:35 -0400 Subject: [PATCH] Agregada documentacion a las clases del framework --- .../xyz/danielcortes/framework/BasePanel.java | 8 +++ .../framework/BaseRepository.java | 67 ++++++++++++++----- .../framework/BaseTableModel.java | 47 +++++++++++-- .../framework/ChangeListener.java | 9 +++ .../xyz/danielcortes/framework/Config.java | 9 +++ .../framework/GeneralValidator.java | 9 --- .../danielcortes/framework/JListUtils.java | 16 +++++ .../danielcortes/framework/LoggedEvent.java | 5 +- .../xyz/danielcortes/framework/PanelName.java | 3 + .../xyz/danielcortes/framework/Passwords.java | 23 +++++++ .../framework/PersistenceManager.java | 16 ++--- .../danielcortes/framework/TriFunction.java | 8 +++ .../framework/ValidationResult.java | 17 +++-- .../framework/YearAttributeConverter.java | 16 +++++ 14 files changed, 205 insertions(+), 48 deletions(-) diff --git a/src/main/java/xyz/danielcortes/framework/BasePanel.java b/src/main/java/xyz/danielcortes/framework/BasePanel.java index c48b5cd..e10cec7 100644 --- a/src/main/java/xyz/danielcortes/framework/BasePanel.java +++ b/src/main/java/xyz/danielcortes/framework/BasePanel.java @@ -2,7 +2,15 @@ package xyz.danielcortes.framework; import javax.swing.JPanel; +/** + * Clase que deben extender todo los paneles de paneles + */ public abstract class BasePanel { + /** + * Entrega el panel que contiene todo el contenido de la vista + * + * @return JPanel con el contenido de la vista + */ public abstract JPanel getContentPane(); } diff --git a/src/main/java/xyz/danielcortes/framework/BaseRepository.java b/src/main/java/xyz/danielcortes/framework/BaseRepository.java index 348efda..bd3ebe3 100644 --- a/src/main/java/xyz/danielcortes/framework/BaseRepository.java +++ b/src/main/java/xyz/danielcortes/framework/BaseRepository.java @@ -1,27 +1,50 @@ package xyz.danielcortes.framework; -import java.util.Collection; import java.util.List; import javax.persistence.EntityManager; import javax.persistence.PersistenceException; import javax.persistence.criteria.CriteriaQuery; +/** + * Repositorio generico que implementa la funcionalidad basica de obtener, guardar, editar y eliminar un modelo + * + * @param Modelo sobre el cual trabaja + *

+ * TODO Seria bueno que al mismo tiempo como ahora se crean transacciones en cada operacion, el que la clase permite crear transacciones manualmente + * cuando se vea necesario + */ public abstract class BaseRepository { + protected EntityManager em; private Class entityClass; + /** + * Crea un repositorio que desarrollara queries con la entityClass entregada + * + * @param entityClass Clase a la que pertenece el modelo con el que se trabajara + */ public BaseRepository(Class entityClass) { this.em = PersistenceManager.getEntityManager(); this.entityClass = entityClass; } + /** + * Realiza la query que obtiene todos los elementos existentes de la entityE + */ public List getAll() { CriteriaQuery criteriaQuery = this.em.getCriteriaBuilder().createQuery(this.entityClass); criteriaQuery.select(criteriaQuery.from(this.entityClass)); return this.em.createQuery(criteriaQuery).getResultList(); } + /** + * Guarda una entidad dentro de una transaccion + * + * @param entity Entidad a guardar + */ public void save(E entity) { this.em.getTransaction().begin(); @@ -35,6 +58,12 @@ public abstract class BaseRepository { this.em.getTransaction().commit(); } + + /** + * Guarda una lista de entidades dentro de una transaccion + * + * @param entities Lista de entidades a guardar + */ public void save(List entities) { this.em.getTransaction().begin(); @@ -48,6 +77,12 @@ public abstract class BaseRepository { this.em.getTransaction().commit(); } + + /** + * Actualiza una entidad dentro de una transaccion + * + * @param entity Entidad a actualizar + */ public void update(E entity) { this.em.getTransaction().begin(); @@ -61,6 +96,11 @@ public abstract class BaseRepository { this.em.getTransaction().commit(); } + /** + * Actualiza una lista de entidades dentro de una transaccion + * + * @param entities Lista de entidades a guardar + */ public void update(List entities) { this.em.getTransaction().begin(); @@ -74,6 +114,11 @@ public abstract class BaseRepository { this.em.getTransaction().commit(); } + /** + * Elimina una entidad dentro de una transaccion + * + * @param entity Entidad a guardar + */ public void delete(E entity) { this.em.getTransaction().begin(); @@ -87,6 +132,11 @@ public abstract class BaseRepository { this.em.getTransaction().commit(); } + /** + * Elimina una lista de entidades dentro de una transaccion + * + * @param entities Lista de entidades a guardar + */ public void delete(List entities) { this.em.getTransaction().begin(); @@ -99,19 +149,4 @@ public abstract class BaseRepository { this.em.getTransaction().commit(); } - - public void delete(Collection entities) { - this.em.getTransaction().begin(); - - try { - for (E e : entities) { - this.em.remove(e); - } - } catch (PersistenceException e) { - e.printStackTrace(); - this.em.getTransaction().rollback(); - } - - this.em.getTransaction().commit(); - } } diff --git a/src/main/java/xyz/danielcortes/framework/BaseTableModel.java b/src/main/java/xyz/danielcortes/framework/BaseTableModel.java index c79e3af..656d725 100644 --- a/src/main/java/xyz/danielcortes/framework/BaseTableModel.java +++ b/src/main/java/xyz/danielcortes/framework/BaseTableModel.java @@ -21,13 +21,16 @@ public class BaseTableModel extends AbstractTableModel { * posicion de la tabla. * * @param columns Lista de columnas que tendra la tabla de la forma: {"Columna 1", "Columna 2", "Columna 3"}; - * @param valueAt TriFunction la cual recibe por parametros: - La lista de filas de la tabla - Un Integer indicando la fila del que se necesita el - * valor - Un Integer indicando la columna de la que se necesita el valor Y esta debe retornar un objeto con toString para poder ser mostrado en la - * tabla + * @param valueAt TriFunction la cual recibe por parametros: *

- * Se sugiere el siguiente tipo de implementacion para la funcion (row, rowIndex, colIndex) -> { switch (colIndex) { case 0: return - * row.get(rowIndex).getColumn1(); case 1: return row.get(rowIndex).getColumn2(); case 2: return row.get(rowIndex).getColumn3(); case 3: return - * row.get(rowIndex).getColumn4(); } return null; } + * - La lista de filas de la tabla - Un Integer indicando la fila del que se necesita el valor - Un Integer indicando la columna de la que se + * necesita el valor Y esta debe retornar un objeto con toString para poder ser mostrado en la tabla + *

+ * Se sugiere el siguiente tipo de implementacion para la funcion + * + * (row, rowIndex, colIndex) -> { switch (colIndex) { case 0: return row.get(rowIndex).getColumn1(); case 1: return row.get(rowIndex).getColumn2(); + * case 2: return row.get(rowIndex).getColumn3(); case 3: return row.get(rowIndex).getColumn4(); } return null; } + * */ public BaseTableModel(String[] columns, TriFunction, Integer, Integer, Object> valueAt) { super(); @@ -41,6 +44,11 @@ public class BaseTableModel extends AbstractTableModel { return this.columns[index]; } + /** + * Añade una nueva fila a la tabla + * + * @param item Objeto a añadir + */ public void addRow(T item) { this.rows.add(item); this.fireTableRowsInserted(this.getRowCount() - 1, this.getRowCount() - 1); @@ -61,11 +69,21 @@ public class BaseTableModel extends AbstractTableModel { return this.valueAt.apply(this.rows, rowIndex, columnIndex); } + /** + * Remueve una fila dada su index en la tabla + * + * @param row Fila a remover + */ public void removeRow(int row) { this.rows.remove(row); this.fireTableRowsDeleted(row, row); } + /** + * Remueve una fila de la tabla + * + * @param t item a eliminar + */ public void removeRow(T t) { int removed = this.rows.indexOf(t); if (removed != -1) { @@ -74,6 +92,12 @@ public class BaseTableModel extends AbstractTableModel { } } + /** + * Obtiene el objeto que contiene la row + * + * @param row fila de la que se quiere obtener el objeto + * @return El objeto contenido en la fila + */ public T getRow(int row) { if (row > -1 && row < this.getRowCount()) { return this.rows.get(row); @@ -82,16 +106,27 @@ public class BaseTableModel extends AbstractTableModel { } } + /** + * @return Todas las filas existentes + */ public List getRows() { return this.rows; } + /** + * En vez de agregar las filas una por una agrega todas en una sola funcion + * + * @param items Lista de objetos a agregar + */ public void setRows(List items) { this.removeRows(); this.rows.addAll(items); this.fireTableRowsInserted(0, this.getRowCount() - 1); } + /** + * Remueve todas las filas de la tabla + */ public void removeRows() { int rowCount = this.getRowCount(); if (rowCount > 0) { diff --git a/src/main/java/xyz/danielcortes/framework/ChangeListener.java b/src/main/java/xyz/danielcortes/framework/ChangeListener.java index 3c538ec..e4054c5 100644 --- a/src/main/java/xyz/danielcortes/framework/ChangeListener.java +++ b/src/main/java/xyz/danielcortes/framework/ChangeListener.java @@ -3,6 +3,12 @@ package xyz.danielcortes.framework; import javax.swing.event.DocumentEvent; import javax.swing.event.DocumentListener; +/** + * Listenerque extiende de DocumentListener, delegando todos los metodos que tiene este a uno solo + * Es mas que nada para comodidad de implementacion con un solo lambda + * + * @see DocumentListener + */ public interface ChangeListener extends DocumentListener { @Override @@ -20,5 +26,8 @@ public interface ChangeListener extends DocumentListener { this.changed(e); } + /** + * Listener que se ejecutara en cualquier tipo de cambio en un Document + */ void changed(DocumentEvent e); } diff --git a/src/main/java/xyz/danielcortes/framework/Config.java b/src/main/java/xyz/danielcortes/framework/Config.java index 5c46686..1b4ebfa 100644 --- a/src/main/java/xyz/danielcortes/framework/Config.java +++ b/src/main/java/xyz/danielcortes/framework/Config.java @@ -3,6 +3,9 @@ package xyz.danielcortes.framework; import java.io.FileInputStream; import java.util.Properties; +/** + * Clase que carga la configuracion desde el properties configuration.properties + */ public class Config { private static Properties defaultProps = new Properties(); @@ -20,6 +23,12 @@ public class Config { private Config() { } + /** + * Obtiene una propiedad dada su key + * + * @param key nombre de la propiedad + * @return La propiedad entregada o null si no existe + */ public static String get(String key) { return defaultProps.getProperty(key); } diff --git a/src/main/java/xyz/danielcortes/framework/GeneralValidator.java b/src/main/java/xyz/danielcortes/framework/GeneralValidator.java index b6eeb42..f0f6111 100644 --- a/src/main/java/xyz/danielcortes/framework/GeneralValidator.java +++ b/src/main/java/xyz/danielcortes/framework/GeneralValidator.java @@ -8,15 +8,6 @@ public class GeneralValidator { private GeneralValidator() { } - public static boolean isLong(String number) { - try { - Long.parseLong(number); - } catch (NumberFormatException e) { - return false; - } - return true; - } - public static boolean isInteger(String number) { try { Integer.parseInt(number); diff --git a/src/main/java/xyz/danielcortes/framework/JListUtils.java b/src/main/java/xyz/danielcortes/framework/JListUtils.java index b34d60b..2c4e0ab 100644 --- a/src/main/java/xyz/danielcortes/framework/JListUtils.java +++ b/src/main/java/xyz/danielcortes/framework/JListUtils.java @@ -4,11 +4,20 @@ import java.util.List; import javax.swing.JList; import javax.swing.ListModel; +/** + * Clase que existe como helper para JList + */ public class JListUtils { private JListUtils() { } + /** + * Setea una serie de items seleccionados dentro de la jlist entregada + * + * @param list JList en la que se seleccionaran los elementos + * @param values La lista de elementos que se seleccionaran + */ public static void setSelectedValues(JList list, List values) { list.clearSelection(); for (Object value : values) { @@ -20,6 +29,13 @@ public class JListUtils { list.ensureIndexIsVisible(list.getSelectedIndex()); } + /** + * Obtiene el index del objeto entregado dentro de la jlist + * + * @param model ListModel que tiene el objeto buscado + * @param value El objeto al cual se le busca el index + * @return El index del elemento, si no existe, se retornara -1 + */ private static int getIndex(ListModel model, Object value) { if (value == null) { return -1; diff --git a/src/main/java/xyz/danielcortes/framework/LoggedEvent.java b/src/main/java/xyz/danielcortes/framework/LoggedEvent.java index cc99e8a..fce0828 100644 --- a/src/main/java/xyz/danielcortes/framework/LoggedEvent.java +++ b/src/main/java/xyz/danielcortes/framework/LoggedEvent.java @@ -12,7 +12,7 @@ public class LoggedEvent extends EventObject { /** * Crea el objeto y almacena los datos entregados - * + *

* El metodo lanza un {@code IllegalArgumentException} en caso que {@code source} y {@code user} sean nulos. * * @param source El objeto en el que el evento se origino @@ -24,6 +24,9 @@ public class LoggedEvent extends EventObject { this.user = user; } + /** + * @return El usuario que fue logeado + */ public Usuario getUser() { return this.user; } diff --git a/src/main/java/xyz/danielcortes/framework/PanelName.java b/src/main/java/xyz/danielcortes/framework/PanelName.java index d4951f9..bce8914 100644 --- a/src/main/java/xyz/danielcortes/framework/PanelName.java +++ b/src/main/java/xyz/danielcortes/framework/PanelName.java @@ -1,5 +1,8 @@ package xyz.danielcortes.framework; +/** + * Enum que lista todos los paneles existentes en la aplicacion + */ public enum PanelName { EMPTY, diff --git a/src/main/java/xyz/danielcortes/framework/Passwords.java b/src/main/java/xyz/danielcortes/framework/Passwords.java index cb51352..b183e84 100644 --- a/src/main/java/xyz/danielcortes/framework/Passwords.java +++ b/src/main/java/xyz/danielcortes/framework/Passwords.java @@ -8,6 +8,9 @@ import java.util.Random; import javax.crypto.SecretKeyFactory; import javax.crypto.spec.PBEKeySpec; +/** + * Clase encargada de crear y comparar contraseñas de forma segura + */ public class Passwords { private static final Random RANDOM = new SecureRandom(); @@ -17,12 +20,25 @@ public class Passwords { private Passwords() { } + /** + * Genera aleatoriamente un byte[] de tamaño 16 + * + * @return El byte[] generados + */ public static byte[] getNextSalt() { byte[] salt = new byte[16]; RANDOM.nextBytes(salt); return salt; } + /** + * Compara 2 constraseñas, la primera sin hashear aun y la segunda ya hasheada + * + * @param password char[] que contiene la contraseña sin hashear aun + * @param salt byte[] que contiene la sal con la que juntar la contraseña al momento de hashearla + * @param expectedHash byte[] con una contraseña ya hasheada con la que comprar + * @return un boleano indicando que las constraseñas son iguales o no + */ public static boolean isExpectedPassword(char[] password, byte[] salt, byte[] expectedHash) { byte[] pwdHash = hash(password, salt); Arrays.fill(password, Character.MIN_VALUE); @@ -35,6 +51,13 @@ public class Passwords { return true; } + /** + * Hashea una contraseña. + * + * @param password char[] con la contraseña a hashear + * @param salt byte[] con la salt que se le aplicara a la contraseña + * @return byte[] con la constraseña hasheada + */ public static byte[] hash(char[] password, byte[] salt) { PBEKeySpec spec = new PBEKeySpec(password, salt, ITERATIONS, KEY_LENGHT); Arrays.fill(password, Character.MIN_VALUE); diff --git a/src/main/java/xyz/danielcortes/framework/PersistenceManager.java b/src/main/java/xyz/danielcortes/framework/PersistenceManager.java index b7e7b6d..5b5cf0b 100644 --- a/src/main/java/xyz/danielcortes/framework/PersistenceManager.java +++ b/src/main/java/xyz/danielcortes/framework/PersistenceManager.java @@ -4,6 +4,9 @@ import javax.persistence.EntityManager; import javax.persistence.EntityManagerFactory; import javax.persistence.Persistence; +/** + * Clase que inicia el PersistenceManager + */ public class PersistenceManager { private static EntityManagerFactory factory; @@ -17,17 +20,10 @@ public class PersistenceManager { private PersistenceManager() { } + /** + * @return El EntityManager + */ public static EntityManager getEntityManager() { return em; } - - public static void close() { - if (factory != null) { - factory.close(); - } - - if (em != null) { - em.close(); - } - } } diff --git a/src/main/java/xyz/danielcortes/framework/TriFunction.java b/src/main/java/xyz/danielcortes/framework/TriFunction.java index 1ffdf70..bca03a2 100644 --- a/src/main/java/xyz/danielcortes/framework/TriFunction.java +++ b/src/main/java/xyz/danielcortes/framework/TriFunction.java @@ -1,5 +1,13 @@ package xyz.danielcortes.framework; +/** + * Interfaz funcional que puede tomar 3 valores como input + * + * @param Clase del primer valor + * @param Clase del segundo valor + * @param Clase del tercer valor + * @param Clase del valor a retornar + */ public interface TriFunction { D apply(A a, B b, C c); diff --git a/src/main/java/xyz/danielcortes/framework/ValidationResult.java b/src/main/java/xyz/danielcortes/framework/ValidationResult.java index c15ca96..14573bf 100644 --- a/src/main/java/xyz/danielcortes/framework/ValidationResult.java +++ b/src/main/java/xyz/danielcortes/framework/ValidationResult.java @@ -9,24 +9,26 @@ public class ValidationResult { private String title; private boolean hasError; + /** + * Crea una instancia con valores por default, estos indican que no existe error en la validacion + */ private ValidationResult() { this.hasError = false; this.message = "No hubo error"; this.title = "Info"; } + /** + * Crea una instancia con un mensaje entregado, el resto de los campos indican que existe un error + * + * @param message Mensaje que corresponde con el error + */ public ValidationResult(String message) { this.title = "Error"; this.message = message; this.hasError = true; } - public ValidationResult(String message, String title) { - this.title = title; - this.message = message; - this.hasError = true; - } - public String getMessage() { return this.message; } @@ -39,6 +41,9 @@ public class ValidationResult { return this.hasError; } + /** + * Muestra con JOptionPane:showMessageDialog el mensaje indicado al momento de la creacion de la instancia + */ public void showErrorDialog() { if (this.hasError) JOptionPane.showMessageDialog( diff --git a/src/main/java/xyz/danielcortes/framework/YearAttributeConverter.java b/src/main/java/xyz/danielcortes/framework/YearAttributeConverter.java index de5249b..146a29d 100644 --- a/src/main/java/xyz/danielcortes/framework/YearAttributeConverter.java +++ b/src/main/java/xyz/danielcortes/framework/YearAttributeConverter.java @@ -3,9 +3,18 @@ package xyz.danielcortes.framework; import java.time.Year; import javax.persistence.AttributeConverter; +/** + * Converter para JPA Convierte un entre Year y Integer + */ public class YearAttributeConverter implements AttributeConverter { + /** + * Convierte un Year en un Integer + * + * @param year Año a transformar + * @return el año reperesentado en un integer + */ @Override public Integer convertToDatabaseColumn(Year year) { if (year != null) @@ -14,6 +23,13 @@ public class YearAttributeConverter implements AttributeConverter return null; } + + /** + * Convierte un integer en un Year + * + * @param integer Integer a transformar + * @return El Year correspondiente al integer entregado + */ @Override public Year convertToEntityAttribute(Integer integer) { if (integer != null)