10.36.4 Prolog Server Interface

The Prolog interface is based on the idea of a Prolog server that provides its service by answering queries from external applications (typically Java applications). The Prolog interface in PrologBeans is defined in library(prologbeans), which implements the Prolog server and exports the following predicates:

start

start(+Options)

starts the Prolog server using the options specified. Please note: start/[0,1] will not return until a server shutdown occurs. Options should be a list of zero or more of:

port(?Val)

an integer denoting the port number of the Prolog server. The default port, if no port option is present, is 8066. In the case of the default port being used, the Socket Reuse Address bit will be set in the underlying sockets layer. If Val is a variable, then some unused port will be selected by the OS, the actual port number can be obtained with get_server_property/1, typically from a server_started event listener.

accepted_hosts(+Val)

a list of atoms denoting the hosts (in form of IP-addresses) that are accepted by the Prolog server (default: ['127.0.0.1']).

session_timeout(+Val)

an integer denoting the duration of a session in seconds. The session will be removed if it has been inactive more than this timeout when the session garbage collect starts. If the session timeout is set to zero, then there will be no garbage collection of sessions (default: 0).

session_gc_timeout(+Val)

an integer denoting the minimum time in seconds between two consecutive session garbage collections. If the timeout is set to zero, then there will be no garbage collection of sessions (default: 0).

For example:

:- start([port(7500),
          accepted_hosts(['127.0.0.1','99.8.7.6'])]).

shutdown

shutdown(+Mode)

shuts down the server and closes the sockets and the streams after processing all available input. There are three modes:

now

as soon as possible (default).

no_sessions

after all sessions have ended (all sessions have either been explicitly removed by request of the client application, or they have been garbage collected). Please note: there can still be connections to the Prolog server even when all sessions have ended.

no_connections

after all connections to the Prolog server are closed. Please note: there can still be user sessions left when all connections have been closed.

register_query(+Query, :PredicateToCall)

register_query(+Query, :PredicateToCall, +SessionVar)

registers a query and the corresponding goal. Before the registration, any previously registered query matching Query will be removed (as if by unregister_query(Query)). The goal PredicateToCall will be called when a query matching Query is received.

Typically, Query and PredicateToCall share variables that are instantiated by the call, and the instantiated Query is passed back to the client. In general, variable bindings can be arbitrary Prolog terms, including terms containing unbound variables. However, any unbound variables with attributes or blocked goals attached to them will be replaced by plain, brand new variables. This is analogous to the way attributed variables are handled in terms that are written, copied, asserted, gathered as solutions to findall/3 and friends, or raised as exceptions. If the attributes must be passed to the client, then the Prolog code can obtain them by using copy_term/3 (see ref-lte-cpt).

The goal is called determinately, i.e. it is never backtracked into. If it fails, then the term no is passed to the client instead of the instantiated Query. If it raises an exception E, then the term error(E) is passed to the client instead of the instantiated Query.

Before calling the query, the variable SessionVar, if given, is bound to the id of the current session. Session ids are typically generated in web applications that track users and mark all consecutive web-accesses with the same session id.

unregister_query(+Query)

unregisters all queries matching Query.

session_get(+SessionID, +ParameterName, +DefaultValue, -Value)

returns the value of a given parameter in a given session. If no value exists, then it will return the default value. Arguments:

SessionID

is the id of the session for which values have been stored

ParameterName

an atom, is the name of the parameter to retrieve

DefaultValue

is the value that will be used if no value is stored

Value

is the stored value or the default value if nothing was stored

session_put(+SessionID, +ParameterName, +Value)

stores the value of the given parameter. Please note: any pre-existing value for this parameter will be overwritten. Note that session_put/3 will not be undone when backtracking (the current implementation is based on assert). Arguments:

SessionID

is the id of the session for the values to store

ParameterName

an atom, is the name of the parameter to store

Value

the value to be stored

register_event_listener(+Event, :PredicateToCall)

register_event_listener(+Event, :PredicateToCall, -Id)

Registers PredicateToCall to be called (as if by once(PredicateToCall)) when the event matching Event occurs (event matching is on principal functor only). If the goal fails or raises an exception, then a warning is written to user_error but the failure or exception is otherwise ignored. Arguments:

Event

is the event template; see below.

PredicateToCall

an arbitrary goal.

Id

becomes bound to a (ground) term that can be used with unregister_event_listener/1 to remove this event listener.

The predefined events are as follows:

session_started(+SessionID)

called before the first call to a query for this session

session_ended(+SessionID)

called before the session is about to be garbage collected (removed)

server_started

called when the server is about to start (enter its main loop)

server_shutdown

called when the server is about to shut down

Attempt to register an event listener for other events than the predefined events will throw an exception.

More than one listeners can be defined for the same event. They will be called in some unspecified order when the event occurs.

unregister_event_listener(+Id)

Unregister a previously registered event listener. The Id is the value returned by the corresponding call to register_event_listener/3. It is an error to attempt to unregister an event listener more than once.