OppoSys - LuaCoffe

LuaCoffe is a framework developed by OppoSys, created in JAVA that aims to enable the fast and efficient creation of Lua applications.

How does it work?

LuaCoffe is a platform that integrates the simplicity and flexibility of the Lua language with the robustness and performance of Java. It uses the LuaJ interpretation API, which allows Lua scripts to be processed on the JVM (Java Virtual Machine), creating a hybrid environment where both worlds coexist efficiently.

LuaCoffe Architecture

At the heart of LuaCoffe is LuaJ and SpringBoot. LuaJ enables the execution of Lua scripts within a Java server created with Tomcat through SpringBoot. The server developed with SpringBoot provides the necessary infrastructure for creating endpoints and managing HTTP calls.

How LuaCoffe Works

The architecture of LuaCoffe allows you to create a Java server (based on Spring Boot) and, within this server, execute Lua scripts through integration with LuaJ. The process unfolds as follows:

1. Execution of Lua Scripts: LuaCoffe uses LuaJ, a library that implements Lua code execution within the JVM. This means Lua scripts can be sent and executed within the Java server, returning results either synchronously or asynchronously, depending on the need.
2. API Creation with Spring Boot: The server is structured with Spring Boot, which manages the creation of RESTful APIs. LuaCoffe simplifies the creation of endpoints on the Java server to expose functionalities, such as GET, POST, and others, and allows these endpoints to execute functions defined in Lua scripts.
3. Integration of Java Modules with Lua: The integration between Lua and Java in LuaCoffe is made through the require() function, which allows the use of Java libraries directly in Lua scripts. This enables developers to write simple Lua code while having access to the full power of Java libraries and frameworks.
4. Facilitating Integration of Java Libraries for Lua Java libraries in LuaCoffe can also be added through the L.C (LuaCoffe) libs table, which allows Java libraries to be used directly in Lua scripts. You can do this through the quick access method luaCoffe.libs

LuaCoffe Setup

Once you clone the LuaCoffe repository, you can start development right away, or configure the development paths in your application.yaml.

Modifying the Paths

To modify the development paths in L.C, access the LuaCoffe configuration file at src/main/resources/application.yaml. This file is responsible for the configuration of the SpringBoot application. Learn more at: Using application.yml vs application.properties in Spring Boot. When you access the folder, you will see something like this:

To change the development folders, you just need to modify the path in

file: 
    path: {development path}
// Inside file, we also have the attribute
package:
    path: {path for scripts to be imported}

where you can also modify the path for scripts that will be used as support for your endpoints. These attributes are responsible for specifying where, in your .../App/.. folder, there will be a scan for the given endpoint.

Creating Endpoints

Creating endpoints in LuaCoffe is extremely simplified; all you need to do is add the mapping tag above your script. However, keep in mind that your script must be inside the path specified in your application.yaml.

file: 
    path: {development path}
    package:
        path: {path for scripts to be imported}

Then you can add the tag luaCoffe.mapping("**method**/any/route/**nameOfYourFile**")
Ex: HelloWorld.lua

    luaCoffe.mapping(get/my/route/HelloWord)
    return {code = 200, response = "Hello, World!"}

It is important to note that without the tag specifying the route for calling your file, it will be closed for calls and cannot be used as an endpoint.

Working with Multiple Scripts import()

When developing web applications, we often face the need to reuse code. The import() in LuaCoffe makes this task easier by allowing multiple Lua scripts to be used together, promoting modularity and reuse of functions and logic across different parts of the application.

With LuaCoffe, you can import any script within the path configured in application.yaml. This allows one script to access functions and variables from another, keeping the code organized and modular. Instead of repeating code, you simply import it where needed.

Example of Script Import

Suppose you have a script mathUtils.lua with mathematical functions that you want to reuse in various parts of the application:

-- mathUtils.lua
MathUtils = {}
MathUtils.__index = MathUtils
function MathUtils:add(a, b)
    return a + b
end

function MathUtils:multiply(a, b)
    return a * b
end
return MathUtils

Now, in another Lua script, you can import mathUtils.lua and use its functions:

-- main.lua
local mathUtils_import = import("mathUtils")
local mathUtils_Class = mathUtils_import();
local mathUtils_Instance = setmetatable({}, mathUtils_Class)

local sumResult = mathUtils:add(10, 20)
local multiplyResult = mathUtils:multiply(5, 4)

return {
    code = 200,
    response = "Result: " .. sumResult .. " and " .. multiplyResult
}

With this, you can easily split the application logic into different files and reuse these functions across various endpoints, keeping the code cleaner and more modular.

Facilitating Integration of External Libraries

LuaCoffe also allows the integration of external libraries both in Lua and in Java. For Lua, the libraries just need to be in the correct directory as specified in application.yaml, and you can import them directly into your scripts. For Java libraries, the framework provides an easy access mechanism through the luaCoffe.libs function, allowing Java functionalities to be exposed and used directly in Lua scripts.

Example of Integration with Java Libraries

Suppose you want to use the OkHttp library to make HTTP requests from a Lua script. On the Java side, the library must already be configured in the classpath, and then you can use it as follows in LuaCoffe:

-- httpClient.lua

function makeRequest(url)
    local req = luaCoffe.lib.luaOkHttp.get(url)
    local response = req
    -- Returns a lua table with the Json values
    return luaCoffe.libs.luaJson.jsonToLua(req)
end

This example shows how it is possible to use the power of Java libraries directly in Lua scripts, enhancing development potential while maintaining Lua's simplicity in the application logic layer.

Working with body request

When working with web development, we often come across the need to work with JSON for communication between machines. In LuaCoffe, it's no different. To wait for the value of an HTTP request in LuaCoffe, we use the waiting.valueOfParam("**parameterName**"). This method works both for sending data through a POST request and for sending parameters through a GET request.

This approach makes it simple and straightforward to extract parameter values sent in the request body (POST) or as part of the URL (GET), allowing real-time data handling and performing actions such as authentication, resource creation, or any other business logic.

    -- Example.lua
    luaCoffe.mapping("post/my/endpoint/Example")
    local myUser = {
        name = waiting.valueOfParam("name"),
        password = waiting.valueOfParam("password")
    }
    return {code = 200, response = myUser}

In the example above, we create an endpoint that extracts the name and password parameters from the HTTP request. These values are captured using waiting.valueOfParam() and returned in a JSON response with an HTTP 200 status code.

Usando classes Java no LuaCoffe

Como o LuaCoffe foi criado em cima da API LuaJ, isso significa que temos todo o poder do LuaJ em nossas mãos. O LuaJ nos disponibiliza diversas bibliotecas para trabalhar com java, para saber mais sobre eles, acesse aqui.

From Luaj - " The Luajava Library The JsePlatform.standardGlobals() includes the luajava library, which simplifies binding to Java classes and methods. It is patterned after the original luajava project. The following lua script will open a swing frame on Java SE:

    	jframe = luajava.bindClass( "javax.swing.JFrame" )
	frame = luajava.newInstance( "javax.swing.JFrame", "Texts" );
	frame:setDefaultCloseOperation(jframe.EXIT_ON_CLOSE)
	frame:setSize(300,400)
	frame:setVisible(true)

See a longer sample in examples/lua/swingapp.lua for details, including a simple animation loop, rendering graphics, mouse and key handling, and image loading. Or try running it using:

java -cp luaj-jse-3.0.2.jar lua examples/lua/swingapp.lua

The Java ME platform does not include this library, and it cannot be made to work because of the lack of a reflection API in Java ME.

The lua connand line tool includes luajava."

LuaJ API Integration

The LuaCoffe framework is built upon the powerful LuaJ API. To explore the full capabilities of LuaJ and understand how it enhances LuaCoffe, check out the official documentation here.

How to Contribute?

There are several ways you can contribute to the development of LuaCoffe. Whether you're experienced with Lua, Java, or simply passionate about helping, your contributions are highly valued. You can help by improving the documentation, writing guides, or providing tutorials that make it easier for new users to get started with the framework. Every bit of effort helps make LuaCoffe more accessible and user-friendly.

If you're more technically inclined, consider contributing by developing new features, fixing bugs, or optimizing the framework's performance. Feel free to explore the codebase, suggest improvements, and submit pull requests. Collaboration is key, and together we can build a more robust and versatile tool for the entire developer community.