From 8cdd25b2623d33ac0e8012b6d9702e6558d284b1 Mon Sep 17 00:00:00 2001 From: Ziver Koc Date: Fri, 2 Oct 2020 00:49:47 +0200 Subject: [PATCH] Cleanup of javadocs --- src/zutil/algo/LevenshteinDistance.java | 4 + src/zutil/chart/AbstractChart.java | 1 + src/zutil/db/DBConnectionPool.java | 78 ++++++++------- src/zutil/db/SQLResultHandler.java | 2 + src/zutil/db/bean/DBBeanObjectDSO.java | 5 +- src/zutil/db/bean/DBBeanSQLResultHandler.java | 95 ++++++++++--------- .../net/threaded/ThreadedUDPNetwork.java | 3 + src/zutil/osal/linux/app/ProcDiskstats.java | 63 ++++++------ 8 files changed, 133 insertions(+), 118 deletions(-) diff --git a/src/zutil/algo/LevenshteinDistance.java b/src/zutil/algo/LevenshteinDistance.java index 5b2cb63..a10fd78 100644 --- a/src/zutil/algo/LevenshteinDistance.java +++ b/src/zutil/algo/LevenshteinDistance.java @@ -33,6 +33,8 @@ public class LevenshteinDistance { * Calculates the Levenshtein Distance(Number of character * changes to equalize the two strings) for two Strings. * + * @param str1 first String to be compared + * @param str2 second string to be compared * @return The number of changes needed to equalize the two Strings */ public static int getDistance(String str1, String str2) { @@ -44,6 +46,8 @@ public class LevenshteinDistance { * Calculates the Levenshtein Distance(Number of character * changes to equalize the two strings) for two Strings. * + * @param str1 first String to be compared + * @param str2 second string to be compared * @param matrix is a int matrix that will be used for the dynamic programing algorithm. * NOTE: matrix must be 1 larger than the largest string * @return The number of changes needed to equalize the two Strings diff --git a/src/zutil/chart/AbstractChart.java b/src/zutil/chart/AbstractChart.java index d671233..e6e969d 100755 --- a/src/zutil/chart/AbstractChart.java +++ b/src/zutil/chart/AbstractChart.java @@ -60,6 +60,7 @@ public abstract class AbstractChart extends JPanel{ * * @param g2 is the Graphics object that will paint the chart * @param bound is the bounds of the axis, the drawing should not exceed this bound + * @return a Rectangle object specifying the drawn are of the axis */ protected abstract Rectangle drawAxis(Graphics2D g2, Rectangle bound); diff --git a/src/zutil/db/DBConnectionPool.java b/src/zutil/db/DBConnectionPool.java index 8b98133..9c03d37 100644 --- a/src/zutil/db/DBConnectionPool.java +++ b/src/zutil/db/DBConnectionPool.java @@ -36,8 +36,8 @@ import java.util.TimerTask; * * @author Ziver */ -public class DBConnectionPool extends TimerTask implements Closeable{ - public static final long DEFAULT_TIMEOUT = 10*60*60*1000; // 10 minutes; +public class DBConnectionPool extends TimerTask implements Closeable { + public static final long DEFAULT_TIMEOUT = 10 * 60 * 60 * 1000; // 10 minutes; public static final int DEFAULT_MAX_SIZE = 5; // DB details @@ -52,26 +52,26 @@ public class DBConnectionPool extends TimerTask implements Closeable{ private long timeout; private Timer timeout_timer; - protected class PoolItem{ + protected class PoolItem { public DBConnection conn; public long timestamp; - public boolean equals(Object o){ + public boolean equals(Object o) { return conn.equals(o); } } // The pool - private LinkedList inusePool; + private LinkedList inUsePool; private LinkedList readyPool; /** * Creates a new pool of DB connections * - * @param dbms is the DB type - * @param url is the URL to the DB - * @param db is the name of the database - * @param user is the user name to the DB + * @param dbms is the DB type + * @param url is the URL to the DB + * @param db is the name of the database + * @param user is the user name to the DB * @param password is the password to the DB */ public DBConnectionPool(DBMS dbms, String url, String db, String user, String password) { @@ -81,7 +81,7 @@ public class DBConnectionPool extends TimerTask implements Closeable{ this.user = user; this.password = password; - inusePool = new LinkedList<>(); + inUsePool = new LinkedList<>(); readyPool = new LinkedList<>(); this.setTimeout(DEFAULT_TIMEOUT); @@ -93,7 +93,7 @@ public class DBConnectionPool extends TimerTask implements Closeable{ * * @param conn is the Connection to register */ - protected void addConnection(DBConnection conn){ + protected void addConnection(DBConnection conn) { PoolItem item = new PoolItem(); item.conn = conn; readyPool.addLast(item); @@ -104,8 +104,8 @@ public class DBConnectionPool extends TimerTask implements Closeable{ * * @param conn is the connection to remove */ - protected void removeConnection(DBConnection conn){ - inusePool.remove(conn); + protected void removeConnection(DBConnection conn) { + inUsePool.remove(conn); readyPool.remove(conn); } @@ -113,20 +113,20 @@ public class DBConnectionPool extends TimerTask implements Closeable{ * Lease one connection from the pool * * @return an DB connection or null if the pool is empty + * @throws Exception will be thrown if there is any issue instantiating a DBConnection */ - public synchronized DBConnection getConnection() throws Exception{ - if(readyPool.isEmpty()){ - if( size() < max_conn ){ + public synchronized DBConnection getConnection() throws Exception { + if (readyPool.isEmpty()) { + if (size() < max_conn) { DBConnection conn = new DBConnection(dbms, url, db, user, password); - conn.setPool( this ); - addConnection( conn ); + conn.setPool(this); + addConnection(conn); return conn; } return null; - } - else{ + } else { PoolItem item = readyPool.poll(); - inusePool.addLast(item); + inUsePool.addLast(item); item.timestamp = System.currentTimeMillis(); return item.conn; } @@ -137,28 +137,29 @@ public class DBConnectionPool extends TimerTask implements Closeable{ * * @param conn is the connection that is not used anymore */ - protected synchronized void releaseConnection(DBConnection conn){ - int index = inusePool.indexOf(conn); - PoolItem item = inusePool.remove(index); + protected synchronized void releaseConnection(DBConnection conn) { + int index = inUsePool.indexOf(conn); + PoolItem item = inUsePool.remove(index); readyPool.addLast(item); } /** * @return the current size of the pool */ - public int size(){ - return inusePool.size() + readyPool.size(); + public int size() { + return inUsePool.size() + readyPool.size(); } /** * Closes all the connections */ - public synchronized void close(){ - for( PoolItem item : inusePool ){ + public synchronized void close() { + for (PoolItem item : inUsePool) { item.conn.forceClose(); } - inusePool.clear(); - for( PoolItem item : readyPool ){ + inUsePool.clear(); + + for (PoolItem item : readyPool) { item.conn.forceClose(); } readyPool.clear(); @@ -166,17 +167,22 @@ public class DBConnectionPool extends TimerTask implements Closeable{ /** * Set the max size of the pool + * + * @param max the new maximum size of the pool */ - public void setMaxSize(int max){ + public void setMaxSize(int max) { this.max_conn = max; } /** * Sets the timeout of the Connections + * + * @param timeout the new timeout value in milliseconds */ - public synchronized void setTimeout(long timeout){ + public synchronized void setTimeout(long timeout) { this.timeout = timeout; - if(timeout_timer!=null) + + if (timeout_timer != null) timeout_timer.cancel(); timeout_timer = new Timer(); timeout_timer.schedule(this, 0, timeout / 2); @@ -185,11 +191,11 @@ public class DBConnectionPool extends TimerTask implements Closeable{ /** * Checks every DB connection if they are valid and has not timed out */ - public void run(){ + public void run() { long stale = System.currentTimeMillis() - timeout; - for(PoolItem item : inusePool){ - if( !item.conn.valid() && stale > item.timestamp ) { + for (PoolItem item : inUsePool) { + if (!item.conn.valid() && stale > item.timestamp) { removeConnection(item.conn); item.conn.forceClose(); } diff --git a/src/zutil/db/SQLResultHandler.java b/src/zutil/db/SQLResultHandler.java index 3c16577..34b76f6 100644 --- a/src/zutil/db/SQLResultHandler.java +++ b/src/zutil/db/SQLResultHandler.java @@ -34,6 +34,8 @@ public interface SQLResultHandler { * * @param stmt is the query * @param result is the ResultSet + * @return a value based on the result handler description + * @throws SQLException if there is any database related issues */ T handleQueryResult(Statement stmt, ResultSet result) throws SQLException; } diff --git a/src/zutil/db/bean/DBBeanObjectDSO.java b/src/zutil/db/bean/DBBeanObjectDSO.java index 68be24c..2f1904e 100755 --- a/src/zutil/db/bean/DBBeanObjectDSO.java +++ b/src/zutil/db/bean/DBBeanObjectDSO.java @@ -10,13 +10,12 @@ import java.sql.SQLException; import java.util.logging.Level; import java.util.logging.Logger; - /** * A intermediate class for loading Objects of generic Classes. * The extending class must set the "superBean" parameter to true in {@link DBBean.DBTable}. * The Object that is stored must use Configurator to define what fields that should be stored. * - * This class needs to fields in DB: + * This class needs two fields in DB: *
    *
  • String type: defining the class name
    • *
  • Text config: the object configuration is stored as JSON
    • @@ -74,6 +73,8 @@ public abstract class DBBeanObjectDSO extends DBBean{ /** * Will replace the current object. + * + * @param obj is the object to set or null to reset the DSO */ public void setObject(T obj){ if(obj != null) { diff --git a/src/zutil/db/bean/DBBeanSQLResultHandler.java b/src/zutil/db/bean/DBBeanSQLResultHandler.java index 217343a..d933987 100755 --- a/src/zutil/db/bean/DBBeanSQLResultHandler.java +++ b/src/zutil/db/bean/DBBeanSQLResultHandler.java @@ -39,7 +39,7 @@ import java.util.List; import java.util.logging.Logger; -public class DBBeanSQLResultHandler implements SQLResultHandler{ +public class DBBeanSQLResultHandler implements SQLResultHandler { private static final Logger logger = LogUtil.getLogger(); private Class beanClass; @@ -48,46 +48,49 @@ public class DBBeanSQLResultHandler implements SQLResultHandler{ private boolean list; - /** * Creates a new instance of this class that returns only one bean * - * @param cl is the DBBean class that will be parsed from the SQL result - * @return a new instance of this class + * @param is the class type that should be instantiated + * @param cl is the DBBean class that will be parsed from the SQL result + * @return a new instance of this class */ - public static DBBeanSQLResultHandler create(Class cl){ + public static DBBeanSQLResultHandler create(Class cl) { return new DBBeanSQLResultHandler<>(cl, null, false); } /** * Creates a new instance of this class that returns a bean with all its containing beans * - * @param cl is the DBBean class that will be parsed from the SQL result - * @param db is the DB connection for loading internal beans - * @return a new instance of this class + * @param is the class type that should be instantiated + * @param cl is the DBBean class that will be parsed from the SQL result + * @param db is the DB connection for loading internal beans + * @return a new instance of this class */ - public static DBBeanSQLResultHandler create(Class cl, DBConnection db){ + public static DBBeanSQLResultHandler create(Class cl, DBConnection db) { return new DBBeanSQLResultHandler<>(cl, db, false); } /** * Creates a new instance of this class that returns a list of beans * - * @param cl is the DBBean class that will be parsed from the SQL result - * @return a new instance of this class + * @param is the class type that should be instantiated + * @param cl is the DBBean class that will be parsed from the SQL result + * @return a new instance of this class */ - public static DBBeanSQLResultHandler> createList(Class cl){ + public static DBBeanSQLResultHandler> createList(Class cl) { return new DBBeanSQLResultHandler<>(cl, null, true); } /** * Creates a new instance of this class that returns a list of beans with all the internal beans * - * @param cl is the DBBean class that will be parsed from the SQL result - * @param db is the DB connection for loading internal beans - * @return a new instance of this class + * @param is the class type that should be instantiated + * @param cl is the DBBean class that will be parsed from the SQL result + * @param db is the DB connection for loading internal beans + * @return a new instance of this class */ - public static DBBeanSQLResultHandler> createList(Class cl, DBConnection db){ + public static DBBeanSQLResultHandler> createList(Class cl, DBConnection db) { return new DBBeanSQLResultHandler<>(cl, db, true); } @@ -95,36 +98,35 @@ public class DBBeanSQLResultHandler implements SQLResultHandler{ /** * Creates a new instance of this class * - * @param cl is the DBBean class that will be parsed from the SQL result - * @param db is the DB connection for loading internal beans, may be null to disable internal beans - * @param list is if the handler should return a list of beans instead of one + * @param cl is the DBBean class that will be parsed from the SQL result + * @param db is the DB connection for loading internal beans, may be null to disable internal beans + * @param list is if the handler should return a list of beans instead of one */ protected DBBeanSQLResultHandler(Class cl, DBConnection db, boolean list) { this.beanClass = cl; this.list = list; this.db = db; - this.beanConfig = DBBeanConfig.getBeanConfig( cl ); + this.beanConfig = DBBeanConfig.getBeanConfig(cl); } /** - * Is called to handle a result from a query. + * Is called to handle a result from a query. * - * @param stmt is the query - * @param result is the ResultSet + * @param stmt is the query + * @param result is the ResultSet */ @SuppressWarnings("unchecked") - public T handleQueryResult(Statement stmt, ResultSet result) throws SQLException{ - if( list ){ + public T handleQueryResult(Statement stmt, ResultSet result) throws SQLException { + if (list) { List bean_list = new LinkedList<>(); - while( result.next() ){ + while (result.next()) { DBBean obj = createBean(result); - bean_list.add( obj ); + bean_list.add(obj); } return (T) bean_list; - } - else{ - if( result.next() ){ + } else { + if (result.next()) { return (T) createBean(result); } return null; @@ -136,22 +138,21 @@ public class DBBeanSQLResultHandler implements SQLResultHandler{ /** * Instantiates a new bean and assigns field values from the ResultSet * - * @param result is where the field values for the bean will bee read from, the cursor should be in front of the data - * @return a new instance of the bean + * @param result is where the field values for the bean will bee read from, the cursor should be in front of the data + * @return a new instance of the bean */ - private DBBean createBean(ResultSet result) throws SQLException{ + private DBBean createBean(ResultSet result) throws SQLException { try { - Long id = result.getLong( "id" ); + Long id = result.getLong("id"); // Check cache first DBBean obj = DBBeanCache.get(beanClass, id); - if ( obj == null ) { + if (obj == null) { // Cache miss create a new bean logger.fine("Creating new Bean(" + beanClass.getName() + ") with id: " + id); obj = beanClass.newInstance(); obj.setId(id); - updateBean( result, obj ); - } - else if (DBBeanCache.isOutDated(obj)){ + updateBean(result, obj); + } else if (DBBeanCache.isOutDated(obj)) { // Update fields logger.finer("Bean(" + beanClass.getName() + ") cache to old for id: " + id); updateBean(result, obj); @@ -167,14 +168,14 @@ public class DBBeanSQLResultHandler implements SQLResultHandler{ /** * Updates an existing bean and assigns field values from the ResultSet * - * @param result is where the field values for the bean will be read from, the cursor should be in front of the data - * @param obj is the bean that will be updated + * @param result is where the field values for the bean will be read from, the cursor should be in front of the data + * @param obj is the bean that will be updated */ @SuppressWarnings("unchecked") - private void updateBean(ResultSet result, DBBean obj) throws SQLException{ + private void updateBean(ResultSet result, DBBean obj) throws SQLException { if (obj.readLock.tryLock()) { try { - logger.fine("Updating Bean("+ beanClass.getName() +") with id: "+ obj.getId()); + logger.fine("Updating Bean(" + beanClass.getName() + ") with id: " + obj.getId()); // Read fields for (DBBeanFieldConfig field : beanConfig.getFields()) { String name = field.getName(); @@ -204,11 +205,11 @@ public class DBBeanSQLResultHandler implements SQLResultHandler{ DBBeanConfig subBeanConfig = subBeanField.getSubBeanConfig(); // Load List from link table - String subSql = "SELECT subBeanTable.* FROM "+ - subBeanField.getLinkTableName() +" as linkTable, "+ - subBeanConfig.getTableName() +" as subBeanTable " + - "WHERE linkTable."+subBeanField.getParentIdColumnName()+"=? AND " + - "linkTable."+subBeanConfig.getIdColumnName()+"=subBeanTable."+subBeanConfig.getIdColumnName(); + String subSql = "SELECT subBeanTable.* FROM " + + subBeanField.getLinkTableName() + " as linkTable, " + + subBeanConfig.getTableName() + " as subBeanTable " + + "WHERE linkTable." + subBeanField.getParentIdColumnName() + "=? AND " + + "linkTable." + subBeanConfig.getIdColumnName() + "=subBeanTable." + subBeanConfig.getIdColumnName(); logger.finest("List Load Query: " + subSql); PreparedStatement subStmt = db.getPreparedStatement(subSql); subStmt.setObject(1, obj.getId()); diff --git a/src/zutil/net/threaded/ThreadedUDPNetwork.java b/src/zutil/net/threaded/ThreadedUDPNetwork.java index 0919e30..db7a611 100755 --- a/src/zutil/net/threaded/ThreadedUDPNetwork.java +++ b/src/zutil/net/threaded/ThreadedUDPNetwork.java @@ -49,6 +49,8 @@ public class ThreadedUDPNetwork extends Thread{ /** * Creates a new unicast Client instance of the class + * + * @throws SocketException if there is any issue creating the new socket */ public ThreadedUDPNetwork() throws SocketException{ this.type = UDPType.UNICAST; @@ -61,6 +63,7 @@ public class ThreadedUDPNetwork extends Thread{ * Creates a new unicast Server instance of the class * * @param port is the port that the server should listen to + * @throws SocketException if there is any issue creating the new socket */ public ThreadedUDPNetwork(int port) throws SocketException{ this.type = UDPType.UNICAST; diff --git a/src/zutil/osal/linux/app/ProcDiskstats.java b/src/zutil/osal/linux/app/ProcDiskstats.java index 541379e..783d250 100755 --- a/src/zutil/osal/linux/app/ProcDiskstats.java +++ b/src/zutil/osal/linux/app/ProcDiskstats.java @@ -145,89 +145,86 @@ public class ProcDiskstats { return devName; } /** - * This values increment when an I/O request completes. + * @return number of completed I/O requests. */ public long getReadIO() { return readIO; } /** - * This value increment when an I/O request is merged with an - * already-queued I/O request. + * @return number of merged I/O requests with an already-queued I/O request. */ public long getReadMerges() { return readMerges; } /** - * This value count the number of sectors read from to this - * block device. The "sectors" in question are the standard UNIX 512-byte - * sectors, not any device- or filesystem-specific block size. The - * counter is incremented when the I/O completes. + * @return the number of sectors read from to this block device. + * The "sectors" in question are the standard UNIX 512-byte + * sectors, not any device- or filesystem-specific block size. The + * counter is incremented when the I/O completes. */ public long getReadSectors() { return readSectors; } /** - * This value count the number of milliseconds that I/O requests have - * waited on this block device. If there are multiple I/O requests waiting, - * this value will increase at a rate greater than 1000/second; for - * example, if 60 read requests wait for an average of 30 ms, the read_ticks - * field will increase by 60*30 = 1800. + * @return the number of milliseconds that I/O requests have + * waited on this block device. If there are multiple I/O requests waiting, + * this value will increase at a rate greater than 1000/second; for + * example, if 60 read requests wait for an average of 30 ms, the read_ticks + * field will increase by 60*30 = 1800. */ public long getReadTicks() { return readTicks; } /** - * This values increment when an I/O request completes. + * @return number of completed I/O requests. */ public long getWriteIO() { return writeIO; } /** - * This value increment when an I/O request is merged with an - * already-queued I/O request. + * @return the number of merged I/O requests with an already-queued I/O request. */ public long getWriteMerges() { return writeMerges; } /** - * This value count the number of sectors written to this - * block device. The "sectors" in question are the standard UNIX 512-byte - * sectors, not any device- or filesystem-specific block size. The - * counter is incremented when the I/O completes. + * @return the number of sectors written to this block device. + * The "sectors" in question are the standard UNIX 512-byte + * sectors, not any device- or filesystem-specific block size. + * The counter is incremented when the I/O completes. */ public long getWriteSectors() { return writeSectors; } /** - * This value count the number of milliseconds that I/O requests have - * waited on this block device. If there are multiple I/O requests waiting, - * this value will increase at a rate greater than 1000/second; for - * example, if 60 write requests wait for an average of 30 ms, the write_ticks - * field will increase by 60*30 = 1800. + * @return the number of milliseconds that I/O requests have + * waited on this block device. If there are multiple I/O requests waiting, + * this value will increase at a rate greater than 1000/second; for + * example, if 60 write requests wait for an average of 30 ms, the write_ticks + * field will increase by 60*30 = 1800. */ public long getWriteTicks() { return writeTicks; } /** - * This value counts the number of I/O requests that have been issued to - * the device driver but have not yet completed. It does not include I/O - * requests that are in the queue but not yet issued to the device driver. + * @return the number of I/O requests that have been issued to + * the device driver but have not yet completed. It does not include I/O + * requests that are in the queue but not yet issued to the device driver. */ public long getInFlight() { return inFlight; } /** - * This value counts the number of milliseconds during which the device has - * had I/O requests queued. + * @return the number of milliseconds during which the device has had I/O requests queued. */ public long getIoTicks() { return ioTicks; } /** - * This value counts the number of milliseconds that I/O requests have waited - * on this block device. If there are multiple I/O requests waiting, this - * value will increase as the product of the number of milliseconds times the - * number of requests waiting (see "read ticks" above for an example). + * @return the number of milliseconds that I/O requests have waited + * on this block device. If there are multiple I/O requests waiting, this + * value will increase as the product of the number of milliseconds times the + * number of requests waiting (see "read ticks" above for an example). */ public long getTimeInQueue() { return timeInQueue;