INTERNAL operator

The INTERNAL operator creates an action or an action statement that executes an internal call.

Syntax

An INTERNAL operator may declare a standalone action:

INTERNAL [CLIENT] [syncType] className [(classId1, ..., classIdN)] [NULL]
INTERNAL [syncType] <{anyTokens}> [NULL]

or be used inline as an action statement:

INTERNAL internalCall [PARAMS paramExpr1, ..., paramExprN] [TO propertyId1, ..., propertyIdM]

internalCall — an internal-call target defined by one of the following syntaxes:

DB execStrExpr
CLIENT [syncType] execStrExpr

Description

The INTERNAL operator creates an action or an action statement that runs either Java code in the application-server JVM, a resource in the user's web client, or SQL against the platform's own database — collectively an internal call. The inline statement form is used when the call target (resource name or SQL command) has to be computed at call time.

Parameters

• CLIENT

  Keyword. Targets the user's web client instead of the application-server JVM — a JavaScript function already loaded in the client, or a client-side file (resolution rule on execStrExpr / className below). Without CLIENT the call targets the JVM (a Java class extending InternalAction, or an inline Java snippet). In the inline statement form CLIENT and DB are mutually exclusive and one of them is required.

  A CLIENT JavaScript function receives the call parameters as its leading arguments, followed by the form controller — the same controller a custom view gets, with which it can set the current object, change properties, look up values, and call actions or scripts back on the server. If the function declares parameters beyond those, the call is treated as asynchronous: a success callback is appended after the controller, and a failure callback after it when the function declares one. With no such extra parameter the function's return value is used as the result.

  function reload(controller) { controller.exec('refreshData'); }
  
  function chooseValue(name, controller, resolve, reject) {
      controller.exec('findValue', name).then(resolve, reject);
  }

• syncType

  Keyword. One of:

  • WAIT — synchronous.
  • NOWAIT — asynchronous.

  Only has an effect on CLIENT calls. Without syncType the call is asynchronous; in the inline statement form a non-empty TO additionally forces synchronous execution. For non-CLIENT standalone calls the keyword is accepted by the grammar but ignored.

• className

  String literal. Without CLIENT — fully qualified name of a Java class reachable from the application-server classpath; the class must extend lsfusion.server.physics.dev.integration.internal.to.InternalAction. With CLIENT — name of a client-side resource (resolution rule identical to execStrExpr below).

• classId1, ..., classIdN

  List of class IDs of the created action's parameters. An empty list (()) means the action takes no parameters. Without the list at all, the parameter classes are taken from the surrounding action declaration's typed parameters. Only applies to the className form.

• NULL

  Keyword allowing NULL values to be passed as parameters of the created action. Without NULL any call that passes NULL is skipped silently and control passes to the next statement. Silently ignored when CLIENT is specified.

• anyTokens

  Source code written in Java. Used as the body of the executeInternal method on a class generated by the platform. The only in-scope variable is context of type lsfusion.server.logics.action.controller.context.ExecutionContext<ClassPropertyInterface>. The fragment body is additionally wrapped in try { ... } catch (Exception e) { e.printStackTrace(); }: any exception thrown from the fragment is caught, printed to the application server's stderr, and does not abort the action. To let exceptions propagate normally, use the className form.

• DB

  Keyword. Runs SQL against the platform's own database. Semantics match EXTERNAL SQL — $N parameter substitution, TABLE parameters uploaded as temporary tables, an .sql expression treated as a classpath resource, and DML/SELECT results written to TO properties — except that no connection string is supplied and the call is performed inside the current change session. Mutually exclusive with CLIENT.

• execStrExpr

  Expression. DB: the SQL command. CLIENT: the resource name — a plain identifier ([a-zA-Z0-9_$]+) is resolved as a JavaScript function defined in the client-loaded code; any other value is treated as a client-side file reference and either looked up in the web/ classpath or, if not found there, passed through the application server's file/URL conversion, which also accepts absolute URLs. Scripts, stylesheets and fonts (.js, .css, .ttf, .otf) are recognised by file extension and handled specially on the client; all other file types, including images, are delivered to the client as generic files. A value prefixed with remove unloads the previously-loaded file of the corresponding kind instead of invoking it; this prefix only affects the file branch — with a JavaScript-function target it is silently ignored. File resources do not receive parameters.

• paramExpr1, ..., paramExprN

  List of expressions passed as call parameters ($N substitutions for DB; positional arguments for CLIENT). Without PARAMS the call has no parameters.

• propertyId1, ..., propertyIdM

  List of property IDs (without parameters) into which results are written. For DB, results are written in the order of the corresponding queries; for CLIENT, at most one property is accepted and supplying it also forces synchronous execution. Without TO no result is captured.

Examples

// Java class with explicit parameter classes
showOnMap 'Show on map'
    INTERNAL 'lsfusion.server.logics.classes.data.utils.geo.ShowOnMapAction' (DOUBLE, DOUBLE, MapProvider, BPSTRING[100]);

// Java class accepting NULLs
serviceDBMT 'DB maintenance (multithreaded, threadCount, timeout)'
    INTERNAL 'lsfusion.server.physics.admin.service.action.ServiceDBMultiThreadAction' (INTEGER, INTEGER) NULL;

// inline Java snippet — prints to the application-server console
printlnAction 'Print text to the console' INTERNAL <{ System.out.println("action test"); }>;

// client-side JS function declared as an action, with parameter classes
QZPrint INTERNAL CLIENT 'QZPrint' (JSON, JSON, JSON);

// client-side JS function declared as an action, without parameters
reload INTERNAL CLIENT 'reload';

// inline client call — resource reference is an absolute URL, loaded synchronously
loadMarkdownLibrary() {
    INTERNAL CLIENT WAIT r'https://cdn.jsdelivr.net/npm/marked/marked.min.js';
}

// inline client call — JS function with PARAMS and a single result captured via TO
getCookie(STRING name) {
    LOCAL cookie = STRING();
    INTERNAL CLIENT 'getCookie' PARAMS name TO cookie;
}

// inline SQL — command taken from a property expression and evaluated at call time
runScript(STRING script) {
    INTERNAL DB script;
}

// inline SQL — parameterized query, result written to a TABLE file via TO
loadPrices() {
    EXPORT TABLE FROM bc=barcode(Article a) WHERE name(a) LIKE '%Meat%';
    INTERNAL DB 'select price, barcode from $1' PARAMS exportFile() TO exportFile;
}