Python 7.0pl5 User Manual

DumpletonSoftwareConsultingPty LimitedOSEVersion 7.0pl519 January 2003Copyright  2001-2003 Dumpleton Software Consulting Pty Limitedhttp://www.dscpl.

Python Modules10Module DescriptionsThe Python modules, their names and their purpose are described below.Installation and SetupThe "netsvc"

Servlet Objects100def processContent(self,content):self._content.append(content)self._contentLength = self._contentLength + len(content)if self._conte

Slow HTTP Clients101password = self.field("password")if self.authenticateUser(user,password):self.sendResponse(netsvc.REDIRECT_TEMPORARY)sel

Servlet Objects102self._batch = Noneself._total = Noneself._count = 0self._job = netsvc.Job(self.generateContent)def destroyServlet(self):FormServlet.

Slow HTTP Clients103Note that the Python wrapper around the C++ implementation of the HTTP servlet class performs buff-ering of content and will only

Servlet Objects104

105Servlet PluginsWhen using a file server object with the HTTP servlet framework, it is possible to associate a specialpurpose handler or plugin with

Servlet Plugins106The effect of this registration will be that whenever a file with extension ".py" is requested by a HTTPclient, the plugin

Module Caching107__servlet__ = ServletProxy()Note that an instance of the servlet is created for each request. That is, unlike other similar systemsav

Servlet Plugins108Note that a module imported in this way can use the same mechanism to import further modules withthe dependence on those additional

Plugin Aliasing109a servlet. In this later case, the name of the resource can remain the same, and no references to the re-source need to be changed.T

Additional Information11An OSE installation supports libraries for different architectures. In order that the shared libraries foryour specific platfo

Servlet Plugins110

111Remote AccessThe service agent and message exchange framework operate based on the concept of processes whichare a part of a distributed applicatio

Remote Access112Even if a new protocol comes along, it is a relatively simple matter to incorporate yet another gateway,again without you having to ma

The Client Application113In this example, any HTTP request made using a URL whose path falls under the base URL of "ht-tp://localhost:8000/servic

Remote Access114return host in self._allow:class RpcGateway(netsvc.RpcGateway):def __init__(self,group,users=None):netsvc.RpcGateway.__init__(self,gro

User Defined Types115User Defined TypesThe NET-RPC protocol supports all the types supported by the service agent framework, as well as theconcept of

Remote Access116Managing User SessionsA common practice with web based services is to have a request initiate a unique session for a user.Having opene

Managing User Sessions117plicitly close off the session, it would be automatically closed after a period of 60 seconds of inactivity,or whatever perio

Remote Access118self.cancelTimer("idle")self.destroyReferences()return 0Using the "netrpc" module to access the service, a client

The XML-RPC Gateway119port = 8000group = "web-services"httpd = netsvc.HttpDaemon(port)rpcgw = netsvc.xmlrpc.RpcGateway(group)httpd.attach(&q

Python Modules12

Remote Access120# Explicitly specify use of Python implementation.rpcgw3 = netsvc.xmlrpc.RpcGateway(group,variant="python")Both these Python

The SOAP Gateway121The SOAP GatewayYet another alternative to XML-RPC is the SOAP protocol. A starting point for SOAP is the site "http://www.dev

Remote Access122port = 8000group = "web-services"httpd = netsvc.HttpDaemon(port)rpcgw = netsvc.soap.RpcGateway(group)httpd.attach("/ser

Using Multiple Gateways123called "ServiceFailure". All elements will be qualified in the OSE namespace. Inadequate priorart has been found a

Remote Access124of also pushing a lot of the security issues onto the main web server where they are more often thannot easier to manage and deal with

13Logging FacilityThe logging facility provides you with a mechanism for generating and capturing messages generatedby your application. These can be

Logging Facility14To log a message, a handle to an instance of the Logger class is acquired and the "notify()"mem-ber function is called.imp

Specifying a Log File15The string used to specify the name of a log file may incorporate the following special tags.When the tags corresponding to dat

Logging Facility16Specifying a Log ChannelWhen logging a message, a log channel may also be specified. If the name of a log channel starts witha chara

Exceptions in a Callback17try:function()except SystemExit:raiseexcept:netsvc.logException()sys.exit()The details of the exception are logged with leve

Logging Facility18

19Program SetupAs Python is an interpreted language, configuration of an application can be carried out by editing theactual scripts. In some circumst

2

Program Setup20import netsvcimport osnetsvc.loadConfig("database.cfg")netsvc.mergeConfig("PWD",os.getcwd())print netsvc.lookupConf

Naming Hierarchies21file = "database.cfg"errors = netsvc.loadConfig(file,None)if errors:errors = "Error reading %s\n%s" % (‘file‘,

Program Setup22To lookup the value of an environment variable the function "lookupEnviron()"isused.Ifanewenvironment variable needs to be se

Process Identity23id1 = netsvc.uniqueId(netsvc.ID_SHORT_FORMAT,"$SID?")The short format identifier is suitable for use within the context of

Program Setup24

25Event FrameworkThe main support for concurrency in the OSE C++ class libraries comes in the form of a mechanismfor building event driven systems. Th

Event Framework26jobs will be reclassified as standard jobs and subsequently executed. When scheduling a job, if jobs ofthe same type already exist, t

Scheduling a Job27All that is occuring here is that when the "cancel()" member function is called, a flag is set. Whenthe job is executed it

Event Framework28cute()" member function, these will override any which may have been supplied when that instanceof the Job class was created.Rea

Destroying Agents29using the same identifier will first be cancelled. If you want to cancel all jobs scheduled using the"scheduleAction()" m

3Table of ContentsTable of Contents...3Manual Overview ...7Python Modules ...

Event Framework30The member function for setting an alarm is "setAlarm()" and that for starting a timer is "start-Timer()". The fi

Socket Events31class Object(netsvc.Agent):def __init__(self):self.scheduleAction(self.daily,"00***","daily")self.scheduleAction(se

Event Framework32Other possible values for the third argument are SOCKET_POLLOUT and SOCKET_POLLPRI.Thevalue SOCKET_POLLPRI is similar to SOCKET_POLLI

Program Shutdown33ating system is being shutdown. Other uses for program signals are to force an application to reread aconfiguration file.These three

Event Framework34should call this member function. This member function can also be called when an external signalintended to shutdown the program is

Program Shutdown35itly provide the time delay as an argument. If this is done, the argument should express the number offull or partial seconds as a f

Event Framework36Note that whatever mechanism is used to initiate program shutdown using these features, messageswill be displayed via the logger indi

37Service AgentsThe service agent framework in OSE provides request/reply and publish/subscribe features similar tothat found in message oriented midd

Service Agents38The major classes in the OSE C++ class library involved in providing this functionality are theOTC_SVBroker, OTC_SVRegistry and OTC_EV

Service Audience39Service AudienceWhen you create a service, the existance of that service will be broadcast to all connected processes.If you wish to

Table of Contents4Service Lookup ...44Service Reports...47Publishing Reports ...

Service Agents40Service GroupsWhen a service agent is created, the name of the service is notionally listed in a global group. In respectof this globa

Service Registry41Any service agent may make queries against its local service registry and get back an immediate resultwhich reflects the current sta

Service Agents42Member functions of a service binding object which may prove useful include "serviceName()","agentIdentity()", &qu

Service Announcements43Service AnnouncementsIf a service agent subscribes to the registry using a specific service name, the service agent will be no-

Service Agents44Group AnnouncementsIf a service agent subscribes to the service registry using a specific service group, it will be notifiedwhen any s

Service Lookup45class PollingService(netsvc.Service):def __init__(self,name,period=60):netsvc.Service.__init__(self)self._name = nameself._period = pe

Service Agents46

47Service ReportsWhen using the service agent framework, in addition to being able to subscribe to the service registryin order to receive announcemen

Service Reports48Publishing ReportsIf a service agent needs to publish a report, the member function "publishReport()"isused.Inpublishing a

Monitoring Reports49a subscription of "system.*" will match "system.time" and "system.statistics.us-ers", but not "

5Managing User Sessions ...116The XML-RPC Gateway...118The SOAP Gateway...121Using Multiple Gateways...

Service Reports50class Subscriber(netsvc.Service):def __init__(self):netsvc.Service.__init__(self)# subscribe to the service group "publishers&qu

Lifetime of Reports51For such cases, it is possible to supply an optional lifetime for a report. That is, a time in seconds forwhich the report should

Service Reports52Although "purgeReports()" exists specifically to deal with potential performance issues in a verylimited number of cases, t

Identity of Subscribers53A further use of the mechanism for identifying a subscribers identity, is so that subscriptions can betracked and for process

Service Reports54subject corresponding to a log channel, the log messages on that log channel will be intercepted andpublished. This can be useful as

Existence of Publishers55essary to track the lifetime of each. It is also useful where it might be necessary to immediately sendoff a request to each

Service Reports56

57Service RequestsThe ability within the service agent framework to find out what services exist and the ability of a serv-ice agent to publish report

Service Requests58When invoking "serviceEndPoint()", the member function needs to be supplied with either aservice binding object for the pa

Handling a Response59for binding in bindings:service = self.serviceEndPoint(binding)if service:service.reset()Handling a ResponseWhen you send a servi

Table of Contents6

Service Requests60Identifying a ResponseIf a callback is being registered to handle the response from multiple service requests, you will mostlikely n

Detecting a Failure61id = service.reset()self.processResponse(self.resetResponse,id)print "request",binding.agentIdentity(),iddef resetRespo

Service Requests62if failure.origin() == "netsvc" and \failure.error() == netsvc.SERVER_METHOD_UNAVAILABLE:# method didn’t existAs an altern

Lack of Response63Lack of ResponseWhen you send a request, there is no gaurantee that the remote service agent hasn’t been destroyedeven before it rec

Service Requests64self.processFailure(self.uptimeFailure,id,60)def uptimeResponse(self,result):print resultdef uptimeFailure(self,id,error,description

Generating a Failure65The reason for requiring that methods be explicitly exported is that it would usually be quite dangerousto allow open access to

Service Requests66raised, you should avoid an except clause which catches all exceptions in any code which enclosescode which might call "abortRe

Delaying a Response67When the member function "suspendResponse()" is called, a callback function should be sup-plied as argument which final

Service Requests68Note that "suspendResponse()" and "resumeResponse()" were only added in OSE 7.0pl5and are a layer on top of the

Invalid Request Method69client = self.currentRequest().sender()self._count = self._count + 1name "%s/%d" % (self.serviceName(),self._count)s

7Manual OverviewThis manual covers the Python wrappers around the OSE C++ class library. The wrappers make avail-able functionality related to the log

Service Requests70that the result is returned immediately. Note that since the response is immediate, you can’t call a meth-od which itself would try

71Message ExchangeThe features of the service agent framework may be used standalone within a single process or acrossa set of connected processes. Th

Message Exchange72Exchange InitialisationTo create a message exchange endpoint in a process, the Exchange class is used. When creating aninstance of t

Service Availability73er endpoint and a new client connects, a subscriber to that service in the client will be notified that theservice is available.

Message Exchange74print "%s originally started at %s" % (publisher,str(content))elif subject == "system.time":print "%s was s

Authorisation of Clients75Overriding this method can be useful purely for logging purposes, but might also be used in a clientprocess to trigger an an

Message Exchange76When an application is distributed across multiple machines, it is often the case that even if one ma-chine were to be shutdown, the

Multiple Exchange Groups77With respect to service visibility, a message exchange endpoint will only pass information about serv-ices if the service au

Message Exchange78tached to the default exchange group. Back end services will still be able to see any services on thedefault exchange group which ha

79Message EncodingAs the service agent framework is designed as a distributed system covering multiple programminglanguages, it is necessary that any

Manual Overview8Service Agents Describes how to create service agents, add themto groups, subscribe to announcements regardingspecific services or mem

Message Encoding80Supported Data TypesCommunication between services is mediated through a layer of code which is written in C++. Theonly exception to

Mapping of Scalar Types81For the date and time types, the current Python implementation does not do any checking to determineif the supplied values ar

Message Encoding82If a service is implemented using the OSE C++ class library directly, different size versions of the in-teger and floating point typ

User Defined Types83"xsd:hexBinary" will also be added at some point in the future as well. If you wish to send a Uni-code string, you shoul

Message Encoding84To add a new mapping at global scope the functions "encoder()" and "decoder()" should beused to register functio

Handling Structured Types85ues of the correct type before hand. A service may also override the default decoders for extended typessuch as the date an

Message Encoding86

87Servlet FrameworkThe HTTP servlet framework can be used to provide a window into your application. A number of pre-defined servlets are provided or

Servlet Framework88to provide a servlet to handle the actual request. If no server object is found corresponding to that por-tion of the URL namespace

The File Server89daemon.start()dispatcher.run()When a HTTP server object is registered, the first argument to the "attach()" member function

9Python ModulesOSE includes a number of Python modules. The main module is a wrapper around functionality pro-vided in the OSE C++ class library. Thos

Servlet Framework90When an instance of the FileServer class is created, it must be supplied with the filesystem direc-tory from which files are to be

User Authorisation91If access to a particular client is disallowed, the connection will be dropped immediately. The clientwill not receive any form of

Servlet Framework92return netsvc.ErrorServlet(404)daemon = netsvc.HttpDaemon(8000)server = HttpServer()daemon.attach("/test",server)daemon.s

The Redirect Servlet93The Redirect ServletThe redirect servlet as implemented by the RedirectServlet class would be used when it is nec-essary to redi

Servlet Framework94becomes congested. Although the servlet may be forced to wait before it can send more data, any otherjobs in the event system will

95Servlet ObjectsTo make the most of the HTTP servlet framework it will be necessary to create your own servlets forinteracting with your application.

Servlet Objects96if self.requestMethod() != "GET":self.sendError(400)else:self.sendResponse(200)self.sendHeader("Content-Type",&qu

Delaying a Response97connection. Negotiation of persistent connections between the HTTP client and server is managed byusing special HTTP request and

Servlet Objects98Destruction of ServletsThe destruction of a servlet can come about as a result of two situations. The first situation is where aservl

Processing Content99been derived from the Agent class, this would include calling the "destroyReferences()"member function.Processing Conten