Evergreen DokuWiki

An exported method that logically runs in the (programming language native) namespace of the OpenSRF Application that implements it.

• The first parameter to an OpenSRF Method is an instance of the method's registration information, casted into the class of that method's OpenSRF Application. Remote subrequest methods are casted into the generic class OpenSRF::Application, since the local server may not have access to the actual implementation class.
• The second argument is a OpenSRF::AppRequest or OpenSRF::AppSubrequest object that supports the respond() and status() methods for communicating with the calling client.
• The remaining parameters are the original request parameters as passed by the calling client. These are passed in the original order and format.

A reserved (either explicitly or by convention) prefix for OpenSRF API-Names. The OpenSRF API-Namespace for built in methods common to all OpenSRF Applications is opensrf.system. The OpenSRF Persist Application reserves (by convention) the OpenSRF API-namespace of opensrf.persist, and all of it's methods live inside that prefix.

The OpenSRF API-Namespace qualified, language agnostic name for an exported method. These should follow the industry standard RPC naming convention of "product DOT module DOT (optional object type DOT) method-name DOT variant", though this is not a hard and fast rule.

Examples would be opensrf.system.method with a variant of opensrf.system.method.all, or opensrf.persist.queue.pop.

A generation (as in age) qualifier for a particular exported method. An API-Level is requested on a per-session basis by the client, and any request made durring a particular session carry this API-Level.

Many OpenSRF Methods may be registered with the same API-Name as long as they are registered at different API-Levels. This allows multiple methods with the same name but different signatures to be used in parallel, providing backward compatability to clients at the API-Name level.

Because inter-Application Subrequests each occur within a unique OpenSRF Session, an OpenSRF Application my make a remote subrequest at any API-Level by specifying the desired API-Level during the call to method_lookup().

If API-Level thunking has been enabled for an Application any requests that cannot be fulfilled at a high API-Level will be passed down to a lower API-Level until a method with the correct API-Name is found. If no OpenSRF Method can be found, a MethodNotFound Exception will be sent back to the client.

If API-Level thunking has not been enabled for an OpenSRF Application, a single method may be registered with multiple API-Levels, and the API-Level at which an OpenSRF Method was called is accessable through the OpenSRF Application Instance that is passed as the first argument to the method.

There is one special OpenSRF API-Level. If an OpenSRF Method is registered at API-Level 0 (zero) it is not published via the introspection API, and it is not available as a thunking target. This special level allows for experimental OpenSRF Methods to be run without worrying about poluting the published API-Namespace, and allows for low-level Methods to be implemented using the OpenSRF registration process so that Applications can share internal methods. If the Application developer later decides to publish the API-Level 0 Method to the OpenSRF Network at large he need only register the method at a higher API-Level.

Generally, any code that defines and populates an OpenSRF API-Namespace. Specifically, and within our current codebase, this is a Perl subclass of the OpenSRF::Application module that provides exported methods under one or more OpenSRF API-Namespaces via one or more calls to the register_method() routine with an API-Level of 1 (one) or greater.

The name of a set of running instances of a particular OpenSRF Application. One Application can run in multiple Server Classes if multiple OpenSRF Servers run the Application under different Server Class names.

As an example of a Server Class, the stock Persist OpenSRF Application runs in the server class of opensrf.persist. OpenSRF Server Classes are used to generate the Router Target JIDs.

The specific transport connection that identifies an instance of an Application within a Server Class. One physical host can run multiple Applications and thus Server Classes.

Multiple Servers in a Server Class can be run on the same host, but this does not provide any load balancing or failover benefits. For best results, and for increased robustness, run one OpenSRF Server of each Server Class on each physical host that should be used for load balancing that particular OpenSRF Application.

Once connected to the OpenSRF Jabber Network, a client makes a CONNECT request to the Server Class that implements the methods that the client requires. Assuming a successful connection, this session pins a single backend process for one or more OpenSRF Requests. Each OpenSRF Session is run at a particular OpenSRF API-Level.