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
config.js <--- datasource definition
unprotected
login.js.sql <--- login/password check and creation of user object in HTTPSession
secure
config.js <--- user object presence check in HTTPSession
user
userOperation1.js.sql
userOperation2.js.sql
admin
adminOperation1.js.sql
adminOperation2.js.sql
config.js <--- checks that user object has admin rights
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