Overview

HTTPS SSH
SIMPLE JAVA SCRIPING ENGINE
VERSION 2.1
February 13th, 2017

[1] INTRODUCTION
[2] USAGE
[3] FAQ

[1] INTRODUCTION
====================================

The main purpose of this simplified minimalistic library is to provide a convenient way of extending an application by user-made scripts via an intuitive API, where
scripts are provided in their source form (Java). This library takes care of script indexing, [re]compilation, inter-script dependency management and compiled script caching.
It also provides sample script interfaces and their initializer implementations, that may be used immediately, without designing your own script class initialization strategy.
The scripting engine itself is configurable and may be used to integrate scripts from different sources using different initialization strategies, as well as to seamlessly
integrate its log entries into your logging subsystem.

[2] USAGE
====================================

Starting with this library is as easy as creating a new instance of eu.revengineer.simplejse.JavaClassScriptCache and calling compileAllScripts().
This may range from very easy, when your idea of script integration closely matches one of sample script initializers to pretty hard, if you have a complex script lifecycle
in mind (especially if it involves multi-layer encapsulation and decapsulation of messages transferred between scripts that are about to be decommissioned and their newly initialized
replacements). Aside from that, it is all just about selecting configuration option values. You may also want to store the newly initialized instance if you'd like to recompile
updated scripts, for example.

[3] FAQ
====================================
Q. Why was it decided to release source that is only compatible with Java 8?
A. Good point. The only thing that would change if this library was targeted at Java 6 is that the code would become more bloated. Essentially, there is nothing that makes this a
Java 8 library instead of a Java 6 library (Java 6 introduced the JavaCompiler API). The breaking point in this decision was support for default interface methods in Java 8. It is
just that much more convenient. Plus, this serves as a declaration that future versions of this library are most likely to make use of default methods for backwards compatibility.

Q. FlatClassLoader? Really?
A. As this is a simplified library, it was decided not to spend time on implementing hierarchical script class management. I am fully aware that a flat loader makes every script
recompilation case the worst case available in the hierarchical approach, but inter-script dependencies make the hierarchical management extra complex. It is possible that this
feature will be implemented at a later release, but don't count on it.

Q. What is the reason for @HasScriptDependencies, when everything can be inferred from the package declaration and imports?
A. As this is a simplified library, no explicit parsing/preprocessing is done on script files. Thus the dependency resolution is done via the annotation processor, which is always
capable of parsing any source file whose source level is compatible with the used JDK's source level.
The main issue that prevents SimpleJSE from just parsing the header (namely, import statements) is the fact that classes in the same package do not require explicit import statements.
Without it, the whole source code must be parsed to find the dependencies and link them into one single chain for a FlatClassLoader.