Initializing Brokers

Brokers are the central concept of OiL. They maintain the list of active servants that are able to receive remote invocations. Brokers also create proxies that provide means to perform invocations on remote servants. Basically, brokers can be seen as the way invocation are performed through the distributed environment.

Creation

Brokers are created by operation oil.init([config]) that returns an initialized broker. The optional parameter config is a table containing the description of the parameters used to initialize the broker. If no parameter is informed, then a default broker is created and returned. All future calls to operation oil.init() without a parameter return the same default broker. The config table might contain the field flavor, which defines the flavor used to create the new broker. For more information about flavors, check section Using Flavors. Other additional fields are defined by the underlying RMI protocol selected for the broker. To get details about these additional fields, see the specific documentation of the RMI protocol that your intend to use.

require "oil"

oil.main(function()
  local orb = oil.init{
    flavor = "cooperative;corba.intercepted",
    host = "127.0.0.1",
    port = 80,
  }
  orb:run()
end)

Start Up

Typically, the application calls method run to start processing invocations sent to the broker. This method executes a continuously processing every invocation destined to the servants registered in the broker. The run method only returns when the broker is shutdown.

It is important to notice that no invocation will be dispatched to local servants until the method run of the ORB starts its execution. For instance, suppose a remove servant registry that provides method register(user). Moreover, suppose the implementation of this method accesses some fields of the object user passed as parameter. In such case, if we invoke register(user), where user is a local servant, then all the attempts of the remote servant to access the object user will be held up while method run and the operation will never complete, resulting in a deadlock. To avoid, this problem, a possible solution is to execute method run in a separate thread like in the example below. For more information about threads, check section Cooperative Multithreading

require "oil"

oil.main(function()
  local orb = oil.init()
  
  -- call orb:run() in a new thread
  oil.newthread(orb.run, orb)
  
  -- continue execution while other thread
  -- processes remote invocations.
  registry = orb:newproxy(oil.readfrom("registry.ref"))
  registry:register(user)
end)

Processing

An alternative to method run, which process invocations continuously, is to use a combination of methods pending and step. The former indicates whether a remote invocation is pending to be processed or not. The later is used to process a single invocation request. If no invocation request is pending then step blocks until an invocation request is received. The following code is somewhat equivalent to invoke method run:

while orb:pending() do
  orb:step()
end

This model of execution is useful to integrate OiL with other event loops when multithreading is not available. Note however, that while method run is executing, there is not need to call method step.

Shut Down

Method shutdown is used to stop the invocation processing being performed, and release all the resources currently used by the broker. After a call to this method, no additional invocation is accepted. Any further remote invocation results in errors raised in the client process. However, every pending invocation initiated before the call of shutdown are completed normally. This method can be called at any time when method run is executing, otherwise an exception is raised.

Interface

Fields

types: Internal interface repository used by the ORB.

Methods

deactivate(object): Deactivates a servant by removing its implementation from the object map.
getIR(): Gets the Interface Repository used to retrieve interface definitions.
getLIR(): Gets a reference to the integrated Interface Repository.
loadidl(idlcode): Loads an IDL definition into the internal Interface Repository.
loadidlfile(filename): Loads an IDL file into the internal Interface Repository.
narrow(proxy, [interface]): Narrows an object reference into some more specific interface.
newdecoder(stream): Creates a new value decoder that unmarshal values from an encoded stream.
newencoder(): Creates a new value encoder that marshal values into strings.
newexcept(body): Creates a new exception object with the given body.
newproxy(reference [, kind, [interface]]): Creates a proxy for a remote object from a textual reference.
newservant(impl [, key [, interface]]): Creates a new servant implemented in Lua that supports some interface.
pending(): Checks whether there is some request pending.
run(): Process incoming requests continuously.
setinterceptor([interceptor [, point]]): Defines an interceptor for invocations.
setexcatch(function [, interface]): Defines a exception handling function for proxies.
setIR(remoteIR): Sets the Interface Repository used to retrieve interface definitions.
shutdown(): Stop processing requests and frees all resources used by the ORB.
step(): Waits for an ORB request and process it.
tostring(object): Returns textual information that identifies the servant.

Definitions

pending()

Checks whether there is some request pending. Method used to check whether there is some unprocessed ORB request pending. It returns true if there is some request pending that must be processed by the main ORB or false otherwise.

Return values

ispending boolean Indication that there is some request pending.

Usage:

while orb:pending() do
  orb:step()
end

step()

Waits for an ORB request and process it. Method used to wait for an ORB request and process it. Only one single ORB request is processed at each call. It returns true if no exception is raised during request processing, or nil and the raised exception otherwise.

Return values

`success`	boolean		Indication of success on request processing.
`exception`	table	[occasional]	Exception raised at request processing.

Usage:

while orb:step() do
 print "One more request successfully processed!"
end

run()

Process incoming requests continuously.

Usage:

orb:run()

shutdown()

Stop processing requests and frees all resources used by the ORB.

Usage:

orb:shutdown()

types

Internal Interface Repository used by OiL. This field holds a reference to the object that implement the CORBA's Interface Repository used by the main ORB. It implements the API defined by CORBA's IR plus an operation resolve(spec) that return a registered IDL type description from a specification that might be an repository ID, an absolute name, an IDL description in Lua or an object from a remote IR.

Usage:

local iface = orb.types:lookup("MyModule::MyInterface")
local iface = orb.types:lookup_id("IDL:MyModule/MyInterface:1.0")

loadidl(idlcode)

Loads an IDL definition into the internal Interface Repository. The IDL specified will be parsed by the LuaIDL compiler and the resulting definitions are updated in the internal interface repository. If any errors occurs during the parse no definitions are loaded into the IR.

Parameters:

idlcode string The IDL specification to be loaded into the internal IR

Return values

... table IDL descriptors that represents the loaded definitions.

Usage:

orb:loadidl [[
  interface Hello {
    attribute boolean quiet;
    readonly attribute unsigned long count;
    string say_hello_to(in string msg);
  };
]]

loadidlfile(filename)

Loads an IDL file into the internal Interface Repository. The IDL file specified will be parsed by the LuaIDL compiler and the resulting definitions are updated in the internal interface repository. If any errors occurs during the parse no definitions are loaded into the IR.

Parameters:

filename string Path to the IDL file that must be loaded

Return values

... table IDL descriptors that represents the loaded definitions.

Usage:

orb:loadidlfile "/usr/local/corba/idl/CosNaming.idl"

getLIR()

Gets a reference to the integrated Interface Repository. Method used to retrieve a reference to the integrated Interface Repository. It returns a reference to the object that implements the internal Interface Repository and exports local cached interface definitions.

Return values:

localIR table CORBA object that exports the internal Interface Repository.

Usage:

print("Local IR IOR is:", orb:tostring(orb:getLIR()))

setIR(remoteIR)

Sets the Interface Repository used to retrieve interface definitions. Method used to set the remote Interface Repository that must be used to retrieve interface definitions not stored in the internal IR. Once these definitions are acquired, they are stored in the internal IR.

Parameters:

remoteIR table Proxy for the remote IR to be used

Usage:

orb:setIR(orb:newproxy("corbaloc::coshost:8080/InterfaceRepository"))

getIR()

Gets the Interface Repository used to retrieve interface definitions. Method used to get a reference to the Interface Repository used to retrieve interface definitions not stored in the internal IR.

Return values:

remoteIR table Proxy to the remote IR currently used.

Usage:

orb:getIR():lookup("::MyModule::MyInterface")

newservant(impl [, key, interface])

Creates a new servant from a table containing operations and attribute values. Method used to create a new servant from a table containing attribute values and operation implementations. The value of impl is used as the implementation of the a servant with interface defined by parameter interface (e.g. repository ID or absolute name of a given IDL interface stored in the IR). Optionally, an object key value may be specified to create persistent references. The servant returned by this method offers all servant attributes and methods, as well as implicit basic operations like CORBA's _interface or _is_a. After this call any requests which object key matches the key of the servant are dispatched to its implementation.

Parameters:

`impl`	table		Value used as the servant implementation (may be an indexable value, e.g. userdata with a metatable that defines the __index field)
`interface`	string		Repository ID or absolute name of the interface the object supports
`key`	string	[optional]	User-defined object key used in creation of the object reference

Return values:

object table Servant created.

Usage:

orb:newservant({say_hello_to=print}, "Key", "::HelloWorld::Hello")
orb:newservant({say_hello_to=print}, nil, "::HelloWorld::Hello")
orb:newservant({say_hello_to=print}, nil, "IDL:HelloWorld/Hello:1.0")

deactivate(object)

Deactivates a servant by removing its implementation from the object map. If object is a servant (i.e. the object returned by newservant) then it is deactivated. Alternatively, the object parameter may be the servant's object key. Only in the case that the servant was created with an implicitly created key by the ORB then the object can be the servant's implementation. Since a single implementation object can be used to create many servants with different interface, in this case the type parameter must be provided with the exact servant's interface.

Parameters:

`object`	table\|string		Servant's object key, servant's implementation or servant itself.
`interface`	string	[occasional]	Identification of the servant's interface (e.g. repository ID or absolute name).

Usage:

orb:deactivate(orb:newservant(impl, "::MyInterface", "objkey"))
orb:deactivate("objkey")
orb:deactivate(impl, "MyInterface")

tostring(object)

Returns textual information that identifies the servant. This method is used to get textual information that references a servant or proxy like an IOR (Inter-operable Object Reference).

Parameters:

object table Servant's object key, servant's implementation or servant itself.

Return values:

textualref string Textual reference to the servant.

Usage:

oil.writeto("ref.ior", orb:tostring(orb:newservant(impl, "::Hello")))

newproxy(reference, [interface])

Creates a proxy for a remote object defined by a textual reference. The value of reference must be a string containing reference information of the object the new new proxy will represent like a stringfied IOR (Inter-operable Object Reference) or corbaloc. Optionally, an interface supported by the remote object may be defined, in this case no attempt is made to determine the actual object interface, i.e. no network communication is made to check the object's interface.

Parameters

`reference`	string		Textual representation of object's reference the new proxy will represent.
`kind`	string	[optional]	Name of the kind of proxy that must be created, like 'synchronous', 'asynchronous' or 'protected'.
`interface`	string	[optional]	Interface identification in the interface repository, like a repID or absolute name of a interface the remote object supports (no interface or type check is done).

Return values

proxy table Proxy to the referenced object.

Usage:

orb:newproxy("IOR:00000002B494...")
orb:newproxy("IOR:00000002B494...", "synchronous", "HelloWorld::Hello")
orb:newproxy("IOR:00000002B494...", "asynchronous", "IDL:HelloWorld/Hello:1.0")
orb:newproxy("corbaloc::host:8080/Key", "protected", "IDL:HelloWorld/Hello:1.0")

narrow(proxy, [interface])

Narrows an object reference into some more specific interface. Method used to narrow an object proxy into some more specific interface. If you wish to create a narrowed proxy from an IOR or corbaloc URL, use the newproxy method. The interface the object reference must be narrowed into is defined by the repository ID or absolute name stored in parameter interface. If no interface is defined, then the object reference is narrowed to the most specific interface supported by the CORBA object. Note that in the former case, no attempt is made to determine the actual object interface, i.e. no network communication is made to check the object's interface.

Parameters:

`proxy`	table		Proxy of a CORBA object that must be narrowed
`interface`	string	[optional]	Repository Interface ID or absolute name of the interface the object reference must be narrowed into (no interface or type check is made)

Return values:

proxy table Proxy to the CORBA object narrowed into some interface supported by the CORBA object.

Usage:

orb:narrow(ns:resolve_str("HelloWorld"))
orb:narrow(ns:resolve_str("HelloWorld"), "IDL:HelloWorld/Hello:1.0")
orb:narrow(ns:resolve_str("HelloWorld"), "::HelloWorld::Hello")

See also: newproxy

newdecoder(stream)

Creates a new value decoder that extracts marshaled values from strings. The decoder reads CORBA's CDR encapsulated streams, i.e. includes an indication of the endianess used in value codification.

Parameters:

stream string String containing a stream with marshaled values.

Return values:

decoder object Value decoder that provides operation 'get([type])' to unmarshal values from a marshaled stream.

Usage:

local decoder = orb:newdecoder(stream)
val = decoder:get(oil.corba.idl.sequence{oil.corba.idl.long})
val = decoder:get(orb.types:lookup("MyLongSeq"))

newencoder()

Creates a new value encoder that marshal values into strings. The encoder marshals values in a CORBA's CDR encapsulated stream, i.e. includes an indication of the endianess used in value codification.

Return values:

encoder object Value encoder that provides operation 'put(value, [type])' to marshal values and operation 'getdata()' to get the marshaled stream.

Usage:

local encoder = orb:newencoder()
encoder:put({1,2,3}, oil.corba.idl.sequence{oil.corba.idl.long})
encoder:put({1,2,3}, orb.types:lookup("MyLongSeq"))
io.write(encoder:getdata())

newexcept(body)

Creates a new exception object with the given body. The body must contain the values of the exceptions fields and must also contain the exception identification in index 1 (in CORBA this identification is the repository ID, absolute name, etc.).

Parameters:

body table Exception body with all its field values and exception ID.

Return values:

exception table Exception that provides meta-method __tostring that provides a pretty-printing.

Usage:

error(orb:newexcept{ "::CORBA::INTERNAL", minor_code_value = 2 })

setexcatch(func [, interface])

Defines a exception handling function for proxies. The handling function receives the following parameters:
proxy: object proxy that performed the operation.
exception: exception/error raised.
operation: descriptor of the operation that raised the exception.
If the parameter interface is provided, then the exception handling function will be applied only to proxies of that interface. Exception handling functions are not cumulative. For example, if there is an exception handling function defined for all proxies and another one only for proxies of a given type, then the later will be used for proxies of that given type. Additionally, exceptions handlers are not inherited through interface hierarchies.

Parameters:

func function Exception handling function.

Return values:

interface table [optional] Interface ID of a group of proxies (e.g. repID).

Usage:

orb:setexcatch(function(_, except) error(tostring(except)) end)

setinterceptor([interceptor [, point]])

Sets an interceptor for operation invocations in both client-side or server-side.

Parameters:

`interceptor`	object	[optional]	Interceptor object that must provide the interface described above. If no value or `nil` is provided the the current interceptor is unregistered from the ORB.
`point`	string	[optional]	Defines the points where the interceptor must be invoked. Options are: `"server"` Interceptor is invoked whenever a request to a local servant is received or replied by the ORB. `"client"` Interceptor is invoked whenever a request to a remove servant is sent or received by the ORB. `"corba.server"` Interceptor is invoked whenever a CORBA request to a local servant is received or replied by the ORB. For more information on CORBA interceptors, see Intercepting Invocations `"corba.client"` Interceptor is invoked whenever a CORBA request to a remove servant is sent or received by the ORB. For more information on CORBA interceptors, see Intercepting Invocations