JavaModule - airminer/jnlua GitHub Wiki
The JNLua Java module provides a small but comprehensive set of Lua functions providing Java language support for Lua.
java.require
Syntax:
type, imported = java.require(typeName [, import = false])
The function returns the named Java type. The type name can be one of the eight Java primitive types (byte
, etc.) or a qualified class name or interface name in dot notation. Member types are separated from their parent by $
. More formally, the type name is a binary name as defined by the Java Language Specification.
If the import flag is asserted, the function imports the Java type into the Lua namespace. For example, java.require("java.lang.System", true)
causes the named class to be accessible as java.lang.System
after the function returns.
The function returns the type and a boolean value indicating whether the type was imported into the Lua namespace. The second return value corresponds to the import flag.
Examples:
System = java.require("java.lang.System")
System:currentTimeMillis()
java.require("java.lang.System", true)
java.lang.System:currentTimeMillis()
java.new
Syntax:
array = java.new(type|typeName {, dimension})
The function creates and returns an array of the specified type and with the specified dimensions. The type can be specified as a type or as a type name. The semantics for type names are the same as in the java.require
function. If no dimensions are specified, the function invokes the no-args constructor of the type.
Examples:
byteArray = java.new("byte", 10)
objectClass = java.require("java.lang.Object")
objectArray = java.new(objectClass, 10)
object = java.new(objectClass) -- same as objectClass:new()
java.instanceof
Syntax:
isInstanceOf = java.instanceof(object, type|typeName)
The function tests and returns if the passed object is an instance of the specified type. The type can be specified as a type or as a type name. The semantics for type names are the same as in the java.require() function.
Examples:
Object = java.require("java.lang.Object")
object = Object:new()
assert(java.instanceof(object, Object))
assert(java.instanceof(object, "java.lang.Object"))
byteArray = java.new("byte", 10)
assert(not java.instanceof(byteArray, "byte")) -- byte \!= byte\[\]
java.cast
Syntax:
typedObject = java.cast(value, type|typeName)
The functions casts the passed value to the specified type and returns a typed object. The type can be specified as a type or as a type name. The semantics for type names are the same as in the java.require()
function.
The primary purpose of the function is to resolve ambivalence when invoking overloaded methods.
Example:
StringBuilder = java.require("java.lang.StringBuilder")
sb = StringBuilder:new()
sb:append(1) -- fails due to ambivalence
sb:append(java.cast(1, "int")) -- succeeds
java.proxy
Syntax:
proxy = java.proxy(table, interface|interfaceName {, interface|interfaceName})
The function creates a Java object that implements a list of interfaces. The provided table contains keys matching the method names of the interfaces and values providing the implementation methods as Lua functions.
Example:
-- privilegedAction object
privilegedAction = { hasRun = false }
-- run() method implementation
function privilegedAction:run()
self.hasRun = true
end
-- Create a proxy implementing the PrivilegedAction interface
proxy = java.proxy(privilegedAction, "java.security.PrivilegedAction")
-- Check pre-condition
assert(not privilegedAction.hasRun)
-- Provide the proxy to the Java access controller which will run it
AccessController = java.require("java.security.AccessController")
AccessController:doPrivileged(proxy)
-- Check post-condition
assert(privilegedAction.hasRun)
java.pairs
Syntax:
func, map, initKey = java.pairs(map)
The function provides an iterator for Java maps that can be used in the Lua generic for construct.
As of JNLua 1.0, the function is also provided via the __pairs
metamethod by the default Java reflector, and the standard pairs
function can be used on maps.
Example:
-- Create a Java map
map = java.new("java.util.HashMap")
for i = 1, 10 do
map:put(tostring(i) , i)
end
-- Process the map with java.pairs()
indexes = nil
sum = 0
for k, v in java.pairs(map) do
if indexes then indexes = indexes .. " " .. k else indexes = k end
sum = sum + v
end
print(string.format("The sum of indexes '%s' is %d", indexes, sum))
java.ipairs
Syntax:
func, array, initKey = java.ipairs(array|list)
The function provides an iterator for Java lists and arrays that can be used in the Lua generic for construct. The iterator is 1-based.
As of JNLua 1.0, the function is also provided via the __ipairs
metamethod by the default Java reflector, and the standard ipairs
function can be used on arrays and lists.
Examples:
-- Create a Java list
list = java.new("java.util.ArrayList")
for i = 1, 10 do
list:add(i)
end
-- Process the list with java.ipairs()
sum = 0
for i, v in java.ipairs(list) do
sum = sum + v
end
print(string.format("The list now contains %d elements with a sum of %d.", list:size(), sum))
-- Create a Java array
byteArray = java.new("byte", 10)
-- Process the array with java.ipairs()
count = 0
for i, v in java.ipairs(byteArray) do
byteArray[i] = i
count = count + 1
end
print(string.format("Set %d values in the array of length %d.", count, #byteArray))
java.totable
Syntax:
table = java.totable(list|map)
The function creates wrapper objects for lists or maps that make these Java data types behave like Lua tables. The wrapper objects support access by indexing, thus allowing for cleaner Lua syntax. As in regular Lua tables, assigning nil to an index removes the element at that index. For lists, the wrapper objects also support the #
operator. The wrapper objects can be used wherever a Java List
or Map
is required, such as in the ipairs()
function.
Examples:
-- Create a Java list and wrap it
arrayList = java.new("java.util.ArrayList")
list = java.totable(arrayList)
for i = 1, 10 do
list[i] = i -- same as arrayList:add(i)
end
-- Process the list with java.ipairs()
sum = 0
for i, v in java.ipairs(list) do
assert(list[i] == v) -- same as assert(arrayList:get(i) == v)
sum = sum + v
end
print(string.format("The list now contains %d elements with a sum of %d.", #list, sum)) -- same as print(string.format("...", arrayList:size(), sum))
-- Remove the first two elements from the list
list[1] = nil -- same as arrayList:remove(0)
list[1] = nil -- same as arrayList:remove(0)
print(string.format("The list now contains %d elements.", #list))
-- Create a Java map and wrap it
hashMap = java.new("java.util.HashMap")
map = java.totable(hashMap)
for i = 1, 10 do
map[tostring(i)] = i -- same as hashMap:put(tostring(i) , i)
end
-- Process the map with java.pairs()
indexes = nil
sum = 0
for k, v in java.pairs(map) do
assert(map[k] == v) -- same as assert(hashMap:get(k) == v)
if indexes then indexes = indexes .. " " .. k else indexes = k end
sum = sum + v
end
print(string.format("The sum of indexes '%s' is %d", indexes, sum))
java.elements
Syntax:
func, iterable, initKey = java.elements(iterable)
The function provides an iterator for Java objects implementing the Iterable
interface. The Iterable interface is implemented by Java classes supporting the Java foreach construct. This includes Java collection types such as lists, maps and sets. The iterator returned by the function can be used in the Lua generic for construct.
Example:
-- Create a set and populate it
set = java.new("java.util.HashSet")
for i = 1, 10 do
set:add(i)
end
-- Process the set with java.elements()
sum = 0
for value in java.elements(set) do
sum = sum + value
end
print(string.format("The sum of the values in the set is %d.", sum))
java.fields
Syntax:
func, class|object, initKey = java.fields(class|object)
The function provides an iterator for Java classes and objects that can be used in the Lua generic for construct. The iterator iterates over the static fields of a class or the non-static fields of an object.
Examples:
-- Print static fields of the System class
System = java.require("java.lang.System")
for field, value in java.fields(System) do
print(field)
end
-- Count fields of an object
object = java.new("java.lang.Object")
count = 0
for field, value in java.fields(object) do
count = count + 1
end
print(string.format("Object has %d public fields.", count))
java.methods
Syntax:
func, class|object, initKey = java.methods(class|object)
The function provides an iterator for Java classes and objects that can be used in the Lua generic for construct. The iterator iterates over the static methods of a class or the non-static methods of an object.
Examples:
-- Print static methods of the System class
System = java.require("java.lang.System")
for method, value in java.methods(System) do
print(method)
end
-- Count methods of an object
object = java.new("java.lang.Object")
count = 0
for field, value in java.methods(object) do
count = count + 1
end
print(string.format("Object has %d public methods.", count))
java.properties
Syntax:
func, object, initKey = java.properties(object)
The function provides an iterator for Java objects that can be used in the Lua generic for construct. The iterator iterates over the properties of an object.
Example:
-- Print properties of a Thread object
Thread = java.require("java.lang.Thread")
thread = Thread:currentThread()
for property, value in java.properties(thread) do
print(property)
end