/ 
Business-Bof-0.02
/ Business::Bof::Server::CLI

NAME

Business::Bof::Server::CLI -- Server of The Business Oriented Framework

SYNOPSIS

perl -MBusiness::Bof::Server::CLI -e run -- -c etc/freemoney.xml

DESCRIPTION

The Server of the Business Oriented Framework (bof) will read its configuration parameters from an XML file (see the section "The configuration file" below), and will start listening on the specified port.

The Server uses SOAP as its transport, in principle making it easy to use any language to connect to as a client, and it will answer to these calls:

Method calls

NOTE All method calls (except login, which has only one parameter), depends upon the parameters being named correctly. With SOAP::Lite this is easy using the SOAP::Data::Name method; I'm not sure how it's done in other languages.

login($logInfo)

Login will take a hash reference to login data and validate it against the Framework Database. If it is a valid data pair, it will return a session ID for the client to use in all subsequent calls. The format of the hash is {name => $username, password => $password}

logout($sessionId)

Provide your session ID to this function so it can clean up after you. The server will be grateful ever after!

getData($sessionId, $parms)

getData takes two parameters. The obvious session ID and a hash reference with SOAP name parms. The format of the hash is the same as is used by DBIx::Recordset. E.g.:

my $parms = { '!Table' => 'order, customer', '!TabJoin' => 'order JOIN customer USING (contact_id)', '$where' => 'ordernr = ?', '$values' => [ $ordernr ] };

callMethod($sessionId, $parms)

callMethod will find the class and method, produce a new instant and execute it with the given parameter (SOAP name parms).

It looks like this:

$parms = { class => 'myClass', data => $data, method => 'myMethod', [long => 1, task => 1 ] };

Two modifiers will help the server determine what to do with the call.

If long is defined, the server will handle it as a long running task, spawning a separate process.

If task is defined, the server will not execute the task immediately, but rather save it in the framework's task table. The server will execute it later depending on the server's configuration settings.

cacheData($sessionId, $cachename, $somedata);

The server saves the data with SOAP name data under the name provided with SOAP name name for later retrieval by getCachedata.

getCachedata($sessionId, $cachename);

The server returns the cached data, given the key with SOAP name name.

getClientdata

This method returns the data provided in the ClientSettings section of the BOF server's configuration file. It also provides some additional information about the current session.

getTask($sessionId, $taskId);

The server returns the task with the given taskId.

getTasklist($sessionId);

The server returns the list of tasks.

printFile($sessionId, $parms)

printFile will print a file from Bof's queue system. The given parameter (SOAP name parms) indicates which file is to be printed.

It looks like this:

$parms = { type => 'doc' or 'print', file => $filename, queue => $queuename };

getPrintfile($sessionId, $parms)

getPrintfile works like printFile, exept it returns the file instead of printing it.

getPrintfilelist($sessionId, $parms)

getPrintfilelist returns an array containing information about the files in the chosen queue

$parms = { type => 'doc' or 'print', queue => $queuename };

getQueuelist($sessionId, $parms)

getQueuelist returns an array containing information about the available queues.

$parms = { type => 'doc' or 'print', };

dumpSession

This method will disappear in a future release. It is ony provided right now as a way of debugging the server and the client calls.

Using SOAP::Lite

See Business::Bof::Client for an example of using SOAP::Lite directly with the server. Business::Bof::Client is an easy to use Object Oriented interface to the BOF server. I recommend using it instead of talking directly with the server.

The configuration file

The BOF server needs a configuration file, the name of which has to be given on startup. It's an XML file looking like this:

Server Configuration

The name of this section in the XML file is ServerConfig

home

The place in the file system where the application located. The server expects that there is a src directory here.

appclass

The applications class name.

host

The SOAP host name.

hostname

The SOAP server proxy name.

name

The SOAP server session name.

port

The server's port number.

serviceName

The servers Service Name.

application

The application's name. Freetext, only for display- and logging purpose.

taskDelay

Number of seconds for the task process to sleep. The task process will wake up and look for new tasks in the framework database with this interval.

housekeepingDelay

Number of seconds for the clean up process to sleep. The clean up process will wake up and look for old sessions to purge.

expireAfter

Number of seconds to keep a session alive without activity. The clean up process will check if a session has been idle for more than this period of time, and if so, purge it.

logCheck

Number of seconds to tell the logger after which it will check for changes in the configuration file. Users of log4perl will know what I'm talking about.

Configuration of Framework Database

The name of this section in the XML file is fwdb. The database is a PostgreSQL database.

host

The database host name.

name

The database name.

username

Username that can access the Framework Database.

password

The user's password.

Settings for application objects

The name of this section in the XML file is ServerSettings. Any data in this section will be handed over to the application's new method through a hash ref. This gives the application a chance to know a little about its surroundings, e.g. directories where it may write files.

Settings for client programs

The name of this section in the XML file is ClientSettings. Any data in this section can be retrieved by the client program through the method getClientdata.

The server will also inform the client program about current session data, so please don't use these names in the ClientSettings section:

menu, allowed, userinfo

Business Classes and Methods

The actual classes that the application server will service must adhere to some standards.

The new method

new must accept three parameters, its type, the database handle and the reference to the server settings as provided in the configuration file.

The methods

The individual methods must accept two parameters, the single value (scalar, hash ref or array ref) that the client program sent and a hash ref with the session's user info.

Requirements

PostgreSQL, POE, SOAP::Lite, DateTime, Log4Perl

AUTHOR

Kaare Rasmussen <kar at kakidata.dk>