org.argeo.app.core/src/org/argeo/app/ux/js/JsClient.java

   1 package org.argeo.app.ux.js;
   2
   3 import java.util.Arrays;
   4 import java.util.Locale;
   5 import java.util.Map;
   6 import java.util.StringJoiner;
   7 import java.util.concurrent.CompletionStage;
   8 import java.util.function.Function;
   9
  10 /**
  11  * A remote JavaScript view (typically in a web browser) which is tightly
  12  * integrated with a local UX part.
  13  */
  14 public interface JsClient {
  15
  16         /*
  17          * TO IMPLEMENT
  18          */
  19
  20         /**
  21          * Execute this JavaScript on the client side after making sure that the page
  22          * has been loaded and the map object has been created.
  23          *
  24          * @param js   the JavaScript code, possibly formatted according to
  25          *             {@link String#format}, with {@link Locale#ROOT} as locale (for
  26          *             stability of decimal separator, as expected by JavaScript.
  27          * @param args the optional arguments of
  28          *             {@link String#format(String, Object...)}
  29          */
  30         Object evaluate(String js, Object... args);
  31
  32         /**
  33          * Executes this JavaScript without expecting a return value.
  34          *
  35          * @param js   the JavaScript code, possibly formatted according to
  36          *             {@link String#format}, with {@link Locale#ROOT} as locale (for
  37          *             stability of decimal separator, as expected by JavaScript.
  38          * @param args the optional arguments of
  39          *             {@link String#format(String, Object...)}
  40          */
  41         void execute(String js, Object... args);
  42
  43         /** @return the globally usable function name. */
  44         String createJsFunction(String name, Function<Object[], Object> toDo);
  45
  46         /** Get a global variable name. */
  47         String getJsVarName(String name);
  48
  49         /**
  50          * Completion stage when the client is ready (typically the page has loaded in
  51          * the browser).
  52          */
  53         CompletionStage<Boolean> getReadyStage();
  54
  55         /*
  56          * DEFAULTS
  57          */
  58
  59         default Object callMethod(String jsObject, String methodCall, Object... args) {
  60                 return evaluate(jsObject + '.' + methodCall, args);
  61         }
  62
  63         default void executeMethod(String jsObject, String methodCall, Object... args) {
  64                 execute(jsObject + '.' + methodCall, args);
  65         }
  66
  67         default boolean isInstanceOf(String reference, String jsClass) {
  68                 return (Boolean) evaluate("return "+getJsVarName(reference) + " instanceof " + jsClass);
  69         }
  70
  71         /*
  72          * UTILITIES
  73          */
  74
  75         static String toJsValue(Object o) {
  76                 if (o instanceof CharSequence)
  77                         return '\'' + o.toString() + '\'';
  78                 else if (o instanceof Number)
  79                         return o.toString();
  80                 else if (o instanceof Boolean)
  81                         return o.toString();
  82                 else if (o instanceof Map map)
  83                         return toJsMap(map);
  84                 else if (o instanceof Object[] arr)
  85                         return toJsArray(arr);
  86                 else if (o instanceof int[] arr)
  87                         return toJsArray(arr);
  88                 else if (o instanceof long[] arr)
  89                         return toJsArray(arr);
  90                 else if (o instanceof double[] arr)
  91                         return toJsArray(arr);
  92                 else if (o instanceof AbstractJsObject jsObject) {
  93                         if (jsObject.isNew())
  94                                 return jsObject.newJs();
  95                         else
  96                                 return jsObject.getJsReference();
  97                 } else if (o instanceof JsReference jsReference) {
  98                         return jsReference.get();
  99                 } else
 100                         return '\'' + o.toString() + '\'';
 101         }
 102
 103         static String toJsArgs(Object... arr) {
 104                 StringJoiner sj = new StringJoiner(",");
 105                 for (Object o : arr) {
 106                         sj.add(toJsValue(o));
 107                 }
 108                 return sj.toString();
 109         }
 110
 111         static String toJsArray(Object... arr) {
 112                 StringJoiner sj = new StringJoiner(",", "[", "]");
 113                 for (Object o : arr) {
 114                         sj.add(toJsValue(o));
 115                 }
 116                 return sj.toString();
 117         }
 118
 119         static String toJsArray(String... arr) {
 120                 return toJsArray((Object[]) arr);
 121         }
 122
 123         static String toJsArray(double... arr) {
 124                 return Arrays.toString(arr);
 125         }
 126
 127         static String toJsArray(long... arr) {
 128                 return Arrays.toString(arr);
 129         }
 130
 131         static String toJsArray(int... arr) {
 132                 return Arrays.toString(arr);
 133         }
 134
 135         static String toJsMap(Map<?, ?> map) {
 136                 StringJoiner sj = new StringJoiner(",", "{", "}");
 137                 // TODO escape forbidden characters
 138                 for (Object key : map.keySet()) {
 139                         sj.add("'" + key + "':" + toJsValue(map.get(key)));
 140                 }
 141                 return sj.toString();
 142         }
 143
 144         static String escapeQuotes(String str) {
 145                 return str.replace("'", "\\'").replace("\"", "\\\"");
 146         }
 147
 148 }