OpenInsight OEngineServer
The Revelation Software OEngineServer is a java application designed to:
1. Listen (on a configurable tcp/ip port) for requests from various client applications;
2. Start up, manage, and terminate OpenEngines (OEngines) - the database engine for OpenInsight;
3. Route requests and responses from the clients to the OEngines
It manages communication with the OEngines via Revelation Softwares' REVCAPI interface (through a "Native Methods Interface"). This means that, although java is a cross-platform language and the EngineServer per se can be run on any support java platform, we are in practice limited to Windows platforms unless/until a REVCAPI-like interface is available in any other environment.
It manages communication with the various clients via tcp/ip, using a protocol first described for the "JD3" open source project. This protocol has been extensively extended for the EngineServer, but at its heart it consists of an 8 character "length" string, followed by the actual message content. The content is typically a command code, followed by a delimiter, and then any other parameters needed for that command code.
The EngineServer can also perform some operations independent of any client requests - specifically, a "startup" process, "shutdown" process, and "timer" process can be executed on any OEngines that are created, and an overal "startup" (also known as "coldstart") process can be defined to run when the EngineServer is first started.
The EngineServer is configurable via the "eserver.cfg" configuration file (located in the OI directory), which contains overall server settings as well as default settings for the various types of client connections.The types of client connections available include:
mode -1: "JD3" (stateless, block mode communication, responding to the JD3 list of commands);
mode 0: "Block" (stateless, block mode);
mode 1: "Char" (stateful, character interaction);
mode 2: "Web" (stateless, block mode)
In addition, it is possible to create an additional type of OEngine:
[mode n/a]: "Phantom" (stateful, character interaction - must be spawned from another OEngine)
The client connection type controls how the EngineServer communicates with the OEngine, as well as what is expected of the OEngine itself. When a request comes in while in a "stateless" mode, the EngineServer looks for an OEngine with the specified "signature" (based on the app, user, password, and dispatch routine) in a queue it maintains of "available OEngines"; if one is found, then it is tasked to execute the request, and then released back into the queue. The _client_ is responsible for maintaining any required state information; _any_ of the stateless OEngines may be used to satisfy _any_ requests from _any_ client (so long as it has the required "signature"). Stateful connections, on the other hand, are dedicated to an individual client; the EngineServer maintains a 1-to-1 connection between the client and the OEngine, and thus subsequent requests from the same client will always go to the same OEngine.
The number of OEngines kept in the "available queue", as well as when OEngines should be shut down and removed from the "available queue", is configured in the eserver.cfg file. As mentioned above, it is also possible to configure routines to run at startup, shutdown, and on a "timer-like" event, for these stateless OEngines.
Revelation Software-available clients include the CTO/AREV64 clients (using "char" mode), OECGI2/OECGI3/OECGI4/OI4Web (using "web" mode), and NetOI (using "JD3" or "web" mode); the OIJio library is also available for java developers wishing to communicate with the EngineServer.
Note that the EngineServer is occasionally referred to as the "Socket Server" or "OESocketServer" interchangably.
Running the EngineServer
The EngineServer can be run from the DOS command line via the following command:
java -jar oesocketserver.jar {-l <configfilename>} {-d <debuglevel>}
where <debuglevel> is an optional number ranging from 1 to <n>; the higher the number, the more detailed information is displayed.
Revelation Software also provides a "wrapper" to enable the java command to run as a service; it is installed via the "installapp-nt.bat" routine located in the OESERVER subdirectory of the OpenInsight directory. This bat file reads configuration information from the wrapper.conf file located in the conf subdirectory.
Note that it is possible to run multiple EngineServer services on a single Windows system, but that to do so requires a modification to the installapp-nt.bat file to read a modified wrapper.conf (specifically, the wrapper.console.title, wrapper.ntservice.name, and wrapper.ntservice.displayname should be unique for each service)
