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}
  retain value switch  retain optional  initial {false}
  args  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.

retain

When both this parameter and unique-dirs are true, then the created unique directories will not be deleted when the service exits.

args

Takes a keyed shelf which each service instance can then retrieve using the read-service-arguments function.

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 retain 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 args 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.

Other Library Functions    wsb.add-service    wsb.clear-all-services    wsb.create-server    wsb.dispatch-request    wsb.forward-request    wsb.has-known-request-type    wsb.reader    wsb.read-service-arguments    wsb.remove-service    wsb.request    wsb.request-header    wsb.request-name    wsb.request-type    wsb.server    wsb.service-exists    wsb.set-request-header    wsb.start-servicing-requests    wsb.wait-for-request    wsb.writer

[ INDEX ] [ CONCEPTS ] [ TASKS ] [ SYNTAX ] [ LIBRARIES ] [ LEGACY LIBRARIES ] [ ERRORS ]