Smalltalk/X Webserver

Documentation of class 'HTTPService':

Class: HTTPService

Inheritance
Description
Related information
Class protocol
Instance protocol
Private classes

Inheritance:

   Object
   |
   +--HTTPService
      |
      +--ComancheService
      |
      +--Demos::HelloWorldService
      |
      +--Demos::WebSlideShow
      |
      +--HTTPFileService
      |
      +--HTTPPluggableActionService
      |
      +--HTTPSelectorService
      |
      +--HTTPTentativeObjectService
      |
      +--SeasideService

Package:: stx:goodies/webServer

Category:: Net-Communication-HTTP-Services

Version:: rev: 1.184 date: 2010/03/19 11:44:24; user: cg; file: HTTPService.st directory: goodies/webServer; module: stx stc-classLibrary: webServer

Description:

This is an abstract class, providing common helpers for all http-Services.

An HTTPService registers itself towards an HTTPServer (under a linkName),
and then gets requests forwarded from that HTTPServer.
Registration is by the top linkName - all requests for URLS below that name
are sent as messages to the service 
(a service may also be registered via multiple linkNames).

I have two subclasses (which are also abstract):
    HTTPActionService   - which gets the full request as argument to its #process: method.
and
    HTTPSelectorService - which dispatches to individual processing methods, depending on
                          the URLs next name component.

To aid in programming threadsafe services there is a class named HTTPServiceRequestContext 
that provides an interface to be inherited from. This allows you to store variables on a 
per request basis. For every request an instance of your subclass is created where the 
instance variable request is set. Before passing through the service, initialize is called 
where you can do your own initialization of your variables. This enables you to have request 
dependent state. At the end of the request release is called.

Redefine the class method requestContextClass: for your service that returns your subclass 
of HTTPServiceRequestContext.

See more info in these subclasses and their concrete example subclasses.

Related information:

    HTTPServer
    HTTPActionService
    HTTPSelectorService
    HTTPInterface

Class protocol:

browser interface

iconInBrowserSymbol: can be redefined for a private icon in the browser (for me and my subclasses).
The returned symbol must be a selector of the ToolbarIconLibrary.

class access

defaultReplyPresenterClass
requestContextClass: returns a class which will be create a new instance for every new request
the class have to be inherits from HTTPServiceRequestContext and contains the
request as an instance variable

class initialization

initialize

defaults

canChangeReplyPresenter: answer true, if the service can change its reply presenter.
Subclasses may redefine this
defaultAllowRobots
defaultPassword
defaultRealm
defaultUser
linkName: return the default path (with slash).
Either redefine this method in a concrete subclass,
or redefine the sender, #linkNames (for multiple default linkNames).

** This method raises an error - it must be redefined in concrete classes **
noRealmBehavior: specify how to behave if the service was registered without a realm.
Possible return values:
all - allow access for all
nobody - deny access for all
localHostOnly - only allow for local host
localNetOnly - only allow for local network

default is all here and localHostOnly in MaintenanceService

instance creation

new

queries

isAbstract: if true, its not listed in wellknownServices and cannot be instantiated
isBrowserStartable
isStartableWithStart

queries-service

addToWellKnownClasses
compiledIntoSettingsDialog
isThreadSafe: return true, if this service is threadSafe.
If not, only a single request is passed to the service at any time (by the HTTPServer);
if it is, multiple requests may be served by multiple threads in parallel.
linkNames: return a collection of default pathes (with initial slashes).
Either redefine this in a concrete service, or #linkName (for a single default linkName).
settingsApplicationClass: a SettingsApplication class - or nil (used in the settings dialog if non-nil)
shownInSettingsDialog

registration

availableServiceClassNames
availableServiceClasses
loadedServiceClassNames
loadedServiceClassNamesWithFilter: aBlock
registerServiceIn: anHTTPServer: create a new service and register it as service reachable via the default servicePath on anHTTPServer

** This is an obsolete interface - do not use it (it may vanish in future versions) **
registerServiceOn: anHTTPServer: create a new service and register it as service reachable via the default servicePath on anHTTPServer
unRegisterServiceIn: anHTTPServer: ** This is an obsolete interface - do not use it (it may vanish in future versions) **
unRegisterServiceOn: anHTTPServer: unregister a service class on anHTTPServer
wellknownServiceClassNames: automagically generated - see #availableServiceClassNames.

resources

classResources: if not already loaded, get the classes resourcePack and return it
flushAllClassResources
flushClassResources
update: something with: aParameter from: changedObject: flush resources on language changes

startup

start: start the service on the default web server (8080) if there is one.
If there is none, ask if it should be started
startOn: httpServer: start(restart) the service on the given server.

Instance protocol:

accessing

allowRobots: true, if robots are allowed to enter this service
allowRobots: something: true, if robots are allowed to enter this service
contextForRequest: aRequest
httpServer
httpServer: something
noRealmBehavior: something
realm: something: set the realm - if non-nil, the request must be authorized
replyPresenter: ** This is an obsolete interface - do not use it (it may vanish in future versions) **
replyPresenter: something: ** This is an obsolete interface - do not use it (it may vanish in future versions) **
replyPresenterClass
replyPresenterClass: aClassOrNil
replyPresenterForRequest: aRequest
requestContextForRequest: aRequest
visibleInHomePage
visibleInHomePage: something

authorization

addUser: aUser password: aPassword toRealm: aRealm: this message is sent if a user is added to a realm or changed.
Subclasses may redefine this
authorizeRequest: aRequest: ensure, that a request ist authorized to use this service.
This is the case, if it is authenticated for a user in the services realm
canAuthenticate: aRequest with: authenticator: is it allowed to authenticate using authenticator?
by default, forward to my server. However, individual services might
redefine this to be more or less strict.
noRealmBehavior: specify how to behave if the service was registered without a realm
usersForRealm: aRealm: by default, forward to my server. However, individual services might
redefine this to define their own, private user-groups

initialize & release

initialize
postStopServing: this is sent after the HTTPServer stops to accept connections
Can be redefined in subclasses for doing any actions
preStartServing: this is sent before the HTTPServer starts to accept connections
Can be redefined in subclasses for doing any actions
shutdown: invoked when deregistered, after the last request can be served.
Can be redefined in subclasses to perform service specific cleanup actions.
startup: invoked when registered, before the first request can be served.
Can be redefined in subclasses to perform service specific startup actions.

maintenance html presentation

commonChangeFromRequest: aRequest: extracts parameter from an html-maintenance post-request
(common parameters, valid for all services)
commonInputFieldsForRequest: aRequest change: change: generates the html-fragment for maintenance form
(common fields, valid for all services)
specificChangeFromRequest: aRequest: extracts parameter from an html-maintenance post-request;
service specific - to be redefined by services.
specificInputFieldsForRequest: aRequest: generates the html-fragment for the maintenance form;
service specific - to be redefined by services.

printing

nameInSettingsTable: redefined in ComancheService, which adds the module-name
printOn: aStream

queries

allowRobotsPaths: ** This is an obsolete interface - do not use it (it may vanish in future versions) **
debugErrors: answer true, if we run in debug mode,
i.e., a debugger should be opened on error
forbiddenRobotsPaths: return the disallowed paths for robots
isRunning: answer true if service is running
overallNumberOfRequests: the overall number of incoming requests

queries-service

isAllowedInMaintenanceMode: return true, if this service is also allowed while the server is in maintenance mode
isFileService: anwser true, if this services serves files
linkName: return the pathName of this service (incl. slash);
i.e. if '/Bla' is returned, the service is reached as http://hostname:port/Bla.
If this service is registered under multiple names, only the first is returned here.
linkName: aString: set the pathName of this service (incl. slash);
i.e. if '/Bla' is passed as argument, the service will be reached as http://hostname:port/Bla.
linkNames: return the relative pathName of this service; i.e. if
'Bla' is returned, the service is reached as http://hostname:port/Bla
linkNames: aLinkNameCollection: set the names, under this service may be reaches;
e.g. if you set linkNames to #('/xxx' '/yyy') this service may be reached as both
'http://hostname:port/xxx' and 'http://hostname:port/yyy'
nameInSettingsDialog
realm: return the realm - if non nil, the request must be authorized
settingsApplicationClass: answer a class that represents an Application used to configure
the service's settings - or nil (used in the settings dialog if non-nil)
skipInstvarIndexInDeepCopy: anIndex: answer true, if the instance variable at: anIndex
should not be copied on #deepCopy
suppressInHomePage: answer true, if the service should not be visible in the server's home page

registration

addAuthentificationTo: aServer
addRequiredForeignServicesTo: aServer: hook to allow for a service to register other required services.
Typically, these are required file services for bitmaps or icons.
Redefined in subclasses.
addStandardFileServicesTo: aServer: many services need the files in data/sampleServerDir/files.
This method registers a corresponding file service
isRegistered: answer true, if this service is registered with a server
registerServiceIn: aServer: register myself as service on a single HTTPServer

** This is an obsolete interface - do not use it (it may vanish in future versions) **
registerServiceOn: aServer: register myself as service on a single HTTPServer
release
removeRequiredForeignServicesFrom: aServer
unRegister: unregister myself from my HTTPServer
unRegisterServiceIn: anHTTPServer: ** This is an obsolete interface - do not use it (it may vanish in future versions) **
unRegisterServiceOn: aServer: unregister myself from an HTTPServer

request handling

_process: aRequest: internal processing method: care for synchronization
process: aRequest: all the work is done in this method.
Any service has to implement this method

** This method raises an error - it must be redefined in concrete classes **

settings persistency

elementDescriptorFor: anAspect: support for persistency:
answer the elements to be made persistent with an ObjectCoder
settingSelectors: answer the selectors that are used to configure a service - i.e. those which are
saved in the webServer-settings file.

Private classes:

    NoRealmBehavior

ST/X 6.1.1; WebServer 1.620 at exept:8081; Mon, 21 May 2012 17:54:57 GMT