From dbbb86080e2063b4f00185a2258f9f3c843fa015 Mon Sep 17 00:00:00 2001 From: Amer Agovic Date: Mon, 15 Jan 2024 13:45:17 -0600 Subject: [PATCH] added better comments --- src/main/java/com/reliancy/dbo/SQL.java | 4 +- .../java/com/reliancy/dbo/SQLCleaner.java | 4 +- .../java/com/reliancy/dbo/SQLTerminal.java | 3 +- src/main/java/com/reliancy/jabba/App.java | 3 - .../java/com/reliancy/jabba/ArgsConfig.java | 23 ------ src/main/java/com/reliancy/jabba/Config.java | 17 ++++- .../java/com/reliancy/jabba/FileConfig.java | 35 +-------- .../java/com/reliancy/jabba/FileServer.java | 4 +- .../java/com/reliancy/jabba/JettyApp.java | 33 ++++---- .../com/reliancy/jabba/ResponseEncoder.java | 1 - src/main/java/com/reliancy/rec/Hdr.java | 5 +- src/main/java/com/reliancy/util/Handy.java | 75 +++++++++++++------ .../java/com/reliancy/util/JointIterator.java | 35 +++++++++ src/main/java/com/reliancy/util/Path.java | 1 - 14 files changed, 135 insertions(+), 108 deletions(-) create mode 100644 src/main/java/com/reliancy/util/JointIterator.java diff --git a/src/main/java/com/reliancy/dbo/SQL.java b/src/main/java/com/reliancy/dbo/SQL.java index c781dc4..c6a2f17 100644 --- a/src/main/java/com/reliancy/dbo/SQL.java +++ b/src/main/java/com/reliancy/dbo/SQL.java @@ -198,8 +198,8 @@ public final class SQL implements Appendable{ /** fills params list with non-trivial parameters. * we place this method here to be as close as possible to the one which generates the sql code. * check and check_export must be in synch. - * @param filter - * @param params + * @param filter check operation to perform over conditions. + * @param params extracted params. */ public final void check_export(Check filter,List params) { if(filter.isLeaf()){ diff --git a/src/main/java/com/reliancy/dbo/SQLCleaner.java b/src/main/java/com/reliancy/dbo/SQLCleaner.java index a03bcd8..4d15310 100644 --- a/src/main/java/com/reliancy/dbo/SQLCleaner.java +++ b/src/main/java/com/reliancy/dbo/SQLCleaner.java @@ -132,8 +132,8 @@ public class SQLCleaner implements Closeable{ } /** * This calls one delete. It can and is called from outside in case of nesting when link is external. - * @param rec - * @throws SQLException + * @param rec database object to delete + * @throws SQLException sql related error */ public boolean deleteRecord(DBO rec) throws SQLException{ if(rec==null) return false; diff --git a/src/main/java/com/reliancy/dbo/SQLTerminal.java b/src/main/java/com/reliancy/dbo/SQLTerminal.java index f297da8..92e39f6 100644 --- a/src/main/java/com/reliancy/dbo/SQLTerminal.java +++ b/src/main/java/com/reliancy/dbo/SQLTerminal.java @@ -160,7 +160,8 @@ public class SQLTerminal implements Terminal{ /** * Returns back java class for given id and or name. * The name is not used in default implementation. - * @param typeid + * @param typeid sql type to map + * @return Class matching sql typeid. */ public Class getJavaType(int typeid) { Class ret=getSQL2Java().get(typeid); diff --git a/src/main/java/com/reliancy/jabba/App.java b/src/main/java/com/reliancy/jabba/App.java index 4a43f5a..bed92b8 100644 --- a/src/main/java/com/reliancy/jabba/App.java +++ b/src/main/java/com/reliancy/jabba/App.java @@ -8,10 +8,7 @@ You may not use this file except in compliance with the License. package com.reliancy.jabba; -import java.io.File; import java.io.IOException; -import java.util.logging.Logger; - import com.reliancy.dbo.Terminal; import com.reliancy.jabba.sec.SecurityPolicy; import com.reliancy.util.CodeException; diff --git a/src/main/java/com/reliancy/jabba/ArgsConfig.java b/src/main/java/com/reliancy/jabba/ArgsConfig.java index 013629e..78965ee 100644 --- a/src/main/java/com/reliancy/jabba/ArgsConfig.java +++ b/src/main/java/com/reliancy/jabba/ArgsConfig.java @@ -4,7 +4,6 @@ import java.io.File; import java.io.IOException; import java.util.ArrayList; import java.util.HashMap; -import java.util.Iterator; import java.util.List; import java.util.Map; import java.util.logging.Logger; @@ -20,7 +19,6 @@ import com.reliancy.util.Log; */ public class ArgsConfig extends Config.Base{ final String[] args; - final ArrayList> schema=new ArrayList<>(); String id; public ArgsConfig(String... args){ this.args=args; @@ -166,26 +164,5 @@ public class ArgsConfig extends Config.Base{ } } - @Override - public Config setProperty(Property key, T val) { - props.put(key,val); - return this; - } - @Override - public T delProperty(Property key) { - Object val=props.remove(key); - return key.getTyp().cast(val); - } - @Override - public Iterator> iterator() { - ArrayList> keys=new ArrayList<>(props.keySet()); - return keys.iterator(); - } - @Override - public Config setSchema(Property ...p){ - this.schema.clear(); - for(Property pp:p) schema.add(pp); - return this; - } } diff --git a/src/main/java/com/reliancy/jabba/Config.java b/src/main/java/com/reliancy/jabba/Config.java index 0d5020e..07af4f4 100644 --- a/src/main/java/com/reliancy/jabba/Config.java +++ b/src/main/java/com/reliancy/jabba/Config.java @@ -7,10 +7,11 @@ You may not use this file except in compliance with the License. */ package com.reliancy.jabba; import java.io.IOException; +import java.util.ArrayList; import java.util.Collection; import java.util.HashMap; +import java.util.Iterator; import java.util.List; -import java.util.Set; import java.util.TreeSet; import org.slf4j.Logger; @@ -73,6 +74,7 @@ public interface Config extends Iterable>{ } public static abstract class Base implements Config { protected final HashMap,Object> props=new HashMap<>(); + final ArrayList> schema=new ArrayList<>(); protected Object modified; public boolean isModified(){ return modified!=null; @@ -109,6 +111,17 @@ public interface Config extends Iterable>{ Object val=props.remove(key); return key.getTyp().cast(val); } + @Override + public Iterator> iterator() { + ArrayList> keys=new ArrayList<>(props.keySet()); + return keys.iterator(); + } + @Override + public Config importSchema(boolean do_clear,Property ...p){ + if(do_clear) this.schema.clear(); + for(Property pp:p) schema.add(pp); + return this; + } } public static final Property LOG_LEVEL=new Property<>("LOG_LEVEL",String.class); @@ -130,6 +143,6 @@ public interface Config extends Iterable>{ public Config setProperty(Property key,T val); public T getProperty(Property key,T def); public T delProperty(Property key); - public Config setSchema(Property ...p); + public Config importSchema(boolean clear,Property ...p); } diff --git a/src/main/java/com/reliancy/jabba/FileConfig.java b/src/main/java/com/reliancy/jabba/FileConfig.java index 5bdffda..7856ccf 100644 --- a/src/main/java/com/reliancy/jabba/FileConfig.java +++ b/src/main/java/com/reliancy/jabba/FileConfig.java @@ -8,12 +8,9 @@ You may not use this file except in compliance with the License. package com.reliancy.jabba; import java.io.IOException; -import java.util.ArrayList; -import java.util.Iterator; public class FileConfig extends Config.Base{ final Config parent; - final ArrayList> schema=new ArrayList<>(); String path; public FileConfig(Config parent,String p){ this.parent=parent; @@ -22,9 +19,9 @@ public class FileConfig extends Config.Base{ public FileConfig(String p){ this(null,p); } - public Config clear(){ - props.clear(); - return this; + @Override + public String getId() { + return path; } @Override public Config getParent(){ @@ -41,10 +38,6 @@ public class FileConfig extends Config.Base{ return this; } - @Override - public String getId() { - return path; - } public FileConfig setId(String path) { this.path = path; return this; @@ -72,28 +65,6 @@ public class FileConfig extends Config.Base{ return def; } } - /** - * FileConfig will save property localy so it is perserved even if not later provided. - */ - @Override - public Config setProperty(Config.Property key, T val) { - props.put(key,val); - return this; - } - @Override - public T delProperty(Property key) { - return (T)props.remove(key); - } - @Override - public Iterator> iterator() { - ArrayList> keys=new ArrayList<>(props.keySet()); - return keys.iterator(); - } - public Config setSchema(Property ...p){ - this.schema.clear(); - for(Property pp:p) schema.add(pp); - return this; - } } diff --git a/src/main/java/com/reliancy/jabba/FileServer.java b/src/main/java/com/reliancy/jabba/FileServer.java index c0c0bd2..c78d354 100644 --- a/src/main/java/com/reliancy/jabba/FileServer.java +++ b/src/main/java/com/reliancy/jabba/FileServer.java @@ -158,9 +158,7 @@ public class FileServer extends EndPoint implements AppModule,Resources.PathRewr } /** adds a route which serves files. * if disk_path is ommited (0 len) or null we use Resources.search_path. - * @param url_path - * @param f - * @param disk_path search path for resource + * @param bucket resource holder to add */ public final FileServer addBucket(Bucket bucket){ buckets.add(bucket); diff --git a/src/main/java/com/reliancy/jabba/JettyApp.java b/src/main/java/com/reliancy/jabba/JettyApp.java index b022fb9..9e3d322 100644 --- a/src/main/java/com/reliancy/jabba/JettyApp.java +++ b/src/main/java/com/reliancy/jabba/JettyApp.java @@ -7,7 +7,6 @@ You may not use this file except in compliance with the License. */ package com.reliancy.jabba; -import java.io.File; import java.io.IOException; import java.util.EventListener; @@ -203,6 +202,25 @@ public class JettyApp extends App implements Handler{ Log.cleanup(); // release logging in case we deferred System.gc(); // sweep memory just in caser } + /** Registers a shutdown hook to interrup jetty. + * ctrl-c works but does not perform our shutdown sequence. + * this code interrupts jetty and then waits for app to finish. + */ + public void addShutdownHook(){ + final JettyApp app=this; + Runtime.getRuntime().addShutdownHook(new Thread(() -> { + if(app.isRunning()){ + try { + app.jetty.stop(); + synchronized(app){ + app.wait(5000); + } + } catch (Exception e) { + app.log().error("shutdown cleanup:", e); + } + } + })); + } /** called from begin just before jetty starts. * this method is called before middleware is notified so we can add or adjust config. * override to hook up your application. @@ -240,18 +258,7 @@ public class JettyApp extends App implements Handler{ public static void main( String[] args ) throws Exception{ Config cnf=new ArgsConfig(args).load(); JettyApp app=new JettyApp(); - Runtime.getRuntime().addShutdownHook(new Thread(() -> { - if(app.isRunning()){ - try { - app.jetty.stop(); - synchronized(app){ - app.wait(5000); - } - } catch (Exception e) { - app.log().error("shutdown cleanup:", e); - } - } - })); + app.addShutdownHook(); app.run(cnf); } diff --git a/src/main/java/com/reliancy/jabba/ResponseEncoder.java b/src/main/java/com/reliancy/jabba/ResponseEncoder.java index aa23e20..3e02376 100644 --- a/src/main/java/com/reliancy/jabba/ResponseEncoder.java +++ b/src/main/java/com/reliancy/jabba/ResponseEncoder.java @@ -21,7 +21,6 @@ import java.nio.charset.StandardCharsets; import java.text.MessageFormat; import java.util.Collection; import java.util.Iterator; -import java.util.Locale; /** * This class will replace the Java writer. diff --git a/src/main/java/com/reliancy/rec/Hdr.java b/src/main/java/com/reliancy/rec/Hdr.java index cfa16c9..5034aac 100644 --- a/src/main/java/com/reliancy/rec/Hdr.java +++ b/src/main/java/com/reliancy/rec/Hdr.java @@ -125,8 +125,9 @@ public class Hdr { } /** * this version will get or create a slot by given name. - * @param name - * @return + * @param name slot name + * @param make wether to create if not present + * @return Slot or null. */ public Slot getSlot(String name,boolean make){ int index=indexOf(name); diff --git a/src/main/java/com/reliancy/util/Handy.java b/src/main/java/com/reliancy/util/Handy.java index 6a99470..328e85e 100644 --- a/src/main/java/com/reliancy/util/Handy.java +++ b/src/main/java/com/reliancy/util/Handy.java @@ -17,6 +17,7 @@ import java.util.ArrayList; import java.util.Base64; import java.util.Collection; import java.util.HashMap; +import java.util.Iterator; import java.util.List; import java.util.Map; import java.util.Random; @@ -29,34 +30,57 @@ import java.util.zip.Inflater; */ public final class Handy { public static final String WHITE=" \t\r\f\n"; - /** place left-right around verb.*/ + + /** place left-right around verb. + * @param verb body of text + * @param left to add left of verb + * @param left to add right of verb + * @return adjusted text + * */ public static String wrap(String verb, String left, String right) { if(verb==null) verb=""; if(verb.startsWith(left) && verb.endsWith(right)) return verb; return left+verb.trim()+right; } - /** remove left-right around verb.*/ + /** remove left-right around verb. + * @param verb body of text + * @param left to remove left of verb + * @param left to remove right of verb + * @return adjusted text + **/ public static String unwrap(String verb, String left, String right) { if(verb==null) return verb; String ret=verb.trim(); - if(verb.startsWith(left) && verb.endsWith(right)) ret=verb.substring(1,verb.length()-1); + if(ret.startsWith(left) && ret.endsWith(right)){ + ret=ret.substring(left.length()); + ret=ret.substring(0,ret.length()-right.length()); + } return ret; } - /** remove any chars elements from left of verb. */ + /** remove any chars elements from left of verb. + * @param verb body of text + * @return adjusted text + */ public static String trimLeft(String verb,String chars){ while(verb.length()>0 && chars.indexOf(verb.charAt(0))!=-1){ verb=verb.substring(1); } return verb; } - /** remove any chars elements from right of verb. */ + /** remove any chars elements from right of verb. + * @param verb body of text + * @return adjusted text + */ public static String trimRight(String verb,String chars){ while(verb.length()>0 && chars.indexOf(verb.charAt(verb.length()-1))!=-1){ verb=verb.substring(0,verb.length()-1); } return verb; } - /** remove any chars elements from right and right of verb. */ + /** remove any chars elements from right and right of verb. + * @param verb body of text + * @return adjusted text + */ public static String trimBoth(String verb,String chars){ verb=trimLeft(verb, chars); verb=trimRight(verb, chars); @@ -77,11 +101,10 @@ public final class Handy { public static T nz(T val, T def){ return val!=null?val:def; } - /** - * Will try to convert incoming value to an expected class. - * @param clazz - * @param val - * @return + /** Convert incoming value to an expected class. + * @param clazz expected class + * @param val observed value + * @return val converted to type clazz. */ public static Object normalize(Class clazz, Object val ) { if(val==null) return null; // we are null @@ -145,7 +168,7 @@ public final class Handy { return digitCount>0; } /** - * returns true if the string is null, empty or contains only white space. + * @return true if the string is null, empty or contains only white space. */ public static boolean isBlank(CharSequence str) { int strLen; @@ -330,9 +353,9 @@ public final class Handy { /** Simple XOR encryption of a map of key-value pairs. * We randomize the order of key value pairs to make the string more unpredictable. * Returned string is base64 and web safe - * @param key - * @param m - * @return a string of encoded map key-value pairs which were then encrypted + * @param key encryption key + * @param m map of param-value pairs to encrypt values. + * @return a string of encoded map param-value pairs which were then encrypted */ public static final String encrypt(String key,Map m){ String ret=null; @@ -411,9 +434,9 @@ public final class Handy { } /** * Generates a hash string with the algorithm name prefixed. - * @param message - * @param algorithm - * @return + * @param message text to hash + * @param algorithm algorithm to use + * @return hash digest */ public static String hashString(String message, String algorithm) throws NoSuchAlgorithmException, UnsupportedEncodingException{ if(message==null) return message; @@ -421,6 +444,7 @@ public final class Handy { byte[] hashedBytes = digest.digest(message.getBytes("UTF-8")); return algorithm.toLowerCase()+":"+encodeBase64(hashedBytes); } + /** hash text using sha256. */ public static String hashSHA256(String message){ try{ return hashString(message,"SHA-256"); @@ -454,10 +478,10 @@ public final class Handy { /** * Finds first occurrence of sub inside body with and without case. * We implement this search via a FSM and ignore the case. - * @param body - * @param sub - * @param offset - * @return offset of first occurance + * @param body text to search + * @param sub subsequence to find + * @param offset offset from 0 + * @return offset of next occurance starting at offiset */ public static final int indexOf(CharSequence body,CharSequence sub,int offset){ if(body==null) return -1; @@ -479,6 +503,8 @@ public final class Handy { } /** * Will trim the string from left and right and remove any of the symbols. + * @param trim text to strip + * @param sym set of characters to trim */ public static String trim(String trim,String sym) { if(trim==null || trim.length()==0) return trim; @@ -557,5 +583,8 @@ public final class Handy { public static String[] split(String delim,String str) { return split(delim,str,-1); } - + @SafeVarargs + public static Iterator chainIterators(Iterator...its){ + return new JointIterator(its); + } } diff --git a/src/main/java/com/reliancy/util/JointIterator.java b/src/main/java/com/reliancy/util/JointIterator.java new file mode 100644 index 0000000..31d1814 --- /dev/null +++ b/src/main/java/com/reliancy/util/JointIterator.java @@ -0,0 +1,35 @@ +package com.reliancy.util; + +import java.util.Iterator; +import java.util.NoSuchElementException; + +/** Chains multiple iterators to act as one. + * + */ +public class JointIterator implements Iterator { + final Iterator iterators[]; + int cursor; + @SafeVarargs + public JointIterator(Iterator ...its){ + this.iterators=its; + cursor=0; + } + @Override + public boolean hasNext() { + while(cursor