wsb.add-service

function

Library: Web Services Broker (OMWSB)
Import : omwsb.xmd

Declaration
export external function add-service 
  to                        value server      server
  named                     value string      service-name
  of-type                   value string      type        optional
  handled-by                value string      program
  min-threads               value integer     min         optional      
  max-threads               value integer     max         optional
  using-unique-directories  value switch      unique-dirs optional  initial {false}
  retained-directories value switch  retain optional  initial {false}
  with-arguments  read-only stream args  optional

Argument definitions

server
a server OMX returned by a call to create-server
service-name
the name of the service to register
type
the type of request that is to be serviced
program
the file name of the OmniMark virtual machine code file which is to be run to handle requests of the specified service-name and type
min-threads
the minimum number of threads to prepare for handling this type of action. If not specified, the value of the min-threads argument to create-server is used
max-threads
the maximum number of threads to prepare for handling this type of action. If not specified, the value of the max-threads argument to create-server is used
unique-dirs
When true, a unique directory will be created for each instance of this service, which it can then retrieve using the read-service-arguments function.
retained-directories
When both this parameter and unique-dirs are true, then the created unique directories will not be deleted when the service exits.
with-arguments
Takes a keyed shelf which each service instance can then retrieve using the read-service-arguments function.


Purpose

The wsb.add-service function allows a new service to be added to an already initialized server OMX. This function can be used to initialize the service mapping prior to servicing any requests, as well as allowing services to be dynamically added at runtime. If a service with the same name and type is already in the table, an exception is thrown. Once a service is registered, all incoming requests that match both the service name and the service type are sent to an invocation of the compiled OmniMark program named by the program parameter.

wsb.add-service creates a thread pool with min-threads threads associated with that service. The actual number of running threads at a given time varies based on the current load on that service, but always ranges between min-threads and max-threads.

If unique-dirs is true, the WSB server will create a unique directory for each instance of this service prior to the instance starting. Then, when the instance later shuts down, the directory is deleted. This feature is useful for situations where services need a work area on the filesystem where they won't clash with other currently running services.

The same parameter is available on the create-server function if this functionality is required by all services. In general, this feature should only be enabled for those services which require it, as it does incur a small performance penalty during instance startup.

By default, unique directories will be created in the system temporary directory (often /tmp/ or C:\temp). However, a different directory can be specified as a parameter to the create-server function.

Specifying the retained-directories parameter is primarily useful for debugging a service which creates files and/or directories in its unique directory. This parameter should not be set to true in any other circumstance, as it leaves all the unique directories on the filesystem when the service exits.

When with-arguments is specified, a copy of the passed shelf is made and stored. Each instance of a service can then retrieve a copy of that shelf using the read-service-arguments function. Note that the copies are not shared between service instances, so modifying the shelf in one instance does not affect the shelf in another instance.

See the description of wsb.create-server for further details on the service-name and type parameters.