Default directory

• The defaut LightLink root location in Web context is /WEB-INF/lightlink/
• The defaut LightLink root package in classpath is lightlink/

The choise to hide "lightlink" under WEB-INF/ is related to security concerns. In such way we remove the probability that incorrect configuration will lead to expostion of .js.sql files via HTTP

All files *.js  and *.js.sql located in lightlink subpackages become REST Services or JavaScript API

Exception is made for:

• config.js or config.js.sql files 
• files that starts with a number or any other non-alphabetical character: #@!-, etc

Therefore .js or .js.sql files that are included/called by other services internally and are not supposed to be callable directly must start with a non-alpha carecter, for example “!”. This also allows to quickly distinguish library files and ordinary service files.

1. Files config.js and config.js.sql

Files config.js and config.js.sql are special. They are not exposed as services, and are executed (included) before all other .js or .js.sql in the package and subpackages.

Usually they define datasources and some common settings, but also can include other library files, define reusable functions, perform authentication checks, etc..

Examples :

sql.setConnection("com.mysql.jdbc.Driver","jdbc:mysql://localhost/lightlink?","root","mysql");
sql.getConnection().setAutoCommit(false);

-----

sql.setDataSourceJndi("java:comp/env/jdbc/MainDB");
sql.setFetchSize(100);

-----

var user = session.getAttribute("user");
if (!user || !user.id){
    throw "Auth required";
}

2. Packages Tree Structure

Configuration files can be applied on tree structure by adding some additional configutations or handling steps for subpackages

Example

3. Database connection settings

You can configure LightLink to use you app server connection pool  or direct connection (not recommended for production)

sql.setConnection("com.mysql.jdbc.Driver","jdbc:mysql://localhost/lightlink?","root","mysql");

or

sql.setDataSourceJndi("java:comp/env/jdbc/MainDB");

Additional parameters :

sql.setFetchSize(N); 

(See:  https://docs.oracle.com/javase/8/docs/api/java/sql/ResultSet.html#setFetchSize-int- )

sql.setMaxRows(N);

allowing to limit the maximum number of rows

sql. setQueryTimeout (N);

allowing to limit the maximum query execution time

It’s also possible to change connection setting directly, for example :

sql.getConnection().setAutoCommit(false); // see java.sql.Connection API

4. Transaction settings

Transactions are disabled by default (autocommit=true)

4.1. Unmanaged transactions:

config.js:

sql.setDataSourceJndi("java:comp/env/jdbc/MainDB");
sql.setFetchSize(100);
sql.setAutoCommit(false); // use transactions

4.2. AppServer managed JEE transactions:

config.js:

sql.setDataSourceJndi("java:comp/env/jdbc/MainDB");
sql.setFetchSize(100);
tx.useTxJee(); // use JEE transactions
tx.setTxTimeout(30) // timeout in minutes for TransactionManager.setTransactionTimeout(..)

4.3. Transaction auto commit

Both Managed and unmanaged transactions respect the following rules:

• Upon a successful execution the transaction is automatically comitted.
• In case of error or applicative exception raised by JavaScript or Java code, current transaction is rolled back.

5. Manual transaction operations:

5.1. Unmanaged transactions:

sql.getConnection().rollback();
sql.getConnection().commit(); // .... see java.sql.Connection API

5.2. AppServer managed JEE transactions:

tx.setTxRollbackOnly()

6. Date format configuration

Allowing to define date format for JSON, both for input and output data

Example:

  types.setCustomDatePattern("yyyy-MM-dd HH:mm:ss");

Note that (date) casting will first try to format incomming String as Date using the provided custom date pattern, if failed, it will try out a universal JSON date format : yyyy-MM-dd'T'HH:mm:ss.SSSXXX