eXept Software AG Logo

Smalltalk/X Webserver

Documentation of class 'HTTPService':

Home

Documentation
www.exept.de
Everywhere
for:
 [back]

Class: HTTPService

Inheritance:

   Object
   |
   +--HTTPService
      |
      +--ComancheService
      |
      +--Demos::HelloWorldService
      |
      +--Demos::WebSlideShow
      |
      +--HTTPFileService
      |
      +--HTTPLinkForwardWithEMailService
      |
      +--HTTPPluggableActionService
      |
      +--HTTPRestService
      |
      +--HTTPScriptProviderService
      |
      +--HTTPSelectorService
      |
      +--HTTPTentativeObjectService
      |
      +--SeasideService
Package:
stx:goodies/webServer
Category:
Net-Communication-HTTP-Services
Version:
rev: 1.229 date: 2024/03/05 21:24:27
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.


copyright
COPYRIGHT (c) 2003 by eXept Software AG
             All Rights Reserved

This software is furnished under a license and may be used
only in accordance with the terms of that license and with the
inclusion of the above copyright notice.   This software may not
be provided or otherwise made available to, or used by, any
other person.  No title to or ownership of the software is
hereby transferred.

Class protocol:

browser interface
o  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
o  defaultReplyPresenterClass

o  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
o  initialize
self initialize

defaults
o  canChangeReplyPresenter
answer true, if the service can change its reply presenter.
Subclasses may redefine this

o  defaultAllowRobots

o  defaultPassword

o  defaultRealm

o  defaultServerPort

o  defaultUser

o  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 must be redefined in concrete classes (subclassResponsibility) **

o  linkNames
return a collection of default paths (with initial slashes).
Either redefine this in a concrete service, or #linkName (for a single default linkName).

** This method must be redefined in concrete classes (subclassResponsibility) **

o  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
o  new
(comment from inherited method)
return an instance of myself without indexed variables

queries
o  isAbstract
if true, its not listed in wellknownServices and cannot be instantiated

o  isBrowserStartable
return true, if this is an application class,
which can be started from the browser

o  isStartableWithStart
return true, if this is an application class,
which can be started via #start

queries-service
o  addToWellKnownClasses

o  compiledIntoSettingsDialog

o  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.

o  settingsApplicationClass
a SettingsApplication class - or nil (used in the settings dialog if non-nil)

o  shownInSettingsDialog

registration
o  availableServiceClassNames
must update known classNames

Usage example(s): 

     self availableServiceClassNames

o  availableServiceClasses
self availableServiceClasses

o  loadedServiceClassNames
self loadedServiceClassNames

o  loadedServiceClassNamesWithFilter: aBlock
self loadedServiceClassNames

o  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) **

o  registerServiceOn: anHTTPServer
create a new service and register it as service reachable via the default servicePath on anHTTPServer

o  registerServiceOnPort: aPortNr
ensure that a webserver is running on aPortNr,
create a new service and register it as service reachable via the default servicePath
inside that webserver

o  unRegisterServiceIn: anHTTPServer

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  unRegisterServiceOn: anHTTPServer
unregister a service class on anHTTPServer

o  wellknownServiceClassNames
automagically generated - see #availableServiceClassNames.

resources
o  classResources
if not already loaded, get the classes resourcePack and return it

Usage example(s): 

     Procware::ProcWareService classResources

o  flushAllClassResources

o  flushClassResources

o  update: something with: aParameter from: changedObject
flush resources on language changes

startup
o  start
start the service on the default web server (8080) if there is one.
If there is none, ask if it should be started

o  startOn: httpServer
start(restart) the service on the given server.

Instance protocol:

accessing
o  allowRobots
true, if robots are allowed to enter this service

o  allowRobots: something
true, if robots are allowed to enter this service

o  allowWebSockets: something

o  contextForRequest: aRequest

o  httpServer

o  httpServer: something

o  lastRequest

o  noRealmBehavior: something

o  realm: something
set the realm - if non-nil, the request must be authorized

o  replyPresenter
return the class name of the replyPresenter,
the setter does switch between class name and instance (from old settings files)

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  replyPresenter: something
this has become obsolete, use #replyPresenterClass

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  replyPresenterClass

o  replyPresenterClass: aClassOrNil

o  replyPresenterForRequest: aRequest

o  requestContextForRequest: aRequest

o  visibleInHomePage

o  visibleInHomePage: something

authorization
o  addUser: aUser password: aPassword toRealm: aRealm
this message is sent if a user is added to a realm or changed.
Subclasses may redefine this

o  allowedAuthMethods
answer a collection of allowed authenticatation method names

o  allowedAuthenticationClasses
answer a collection of authenticators that may be used to authenticate

o  authenticationDataForUser: userName inRealm: aRealm
by default, forward to my server. However, individual services might
redefine this to define their own, private user-groups

o  authorizeRequest: aRequest
ensure, that a request is authorized to use this service.
This is the case, if it is authenticated for a user in the services realm

o  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.

o  noRealmBehavior
specify how to behave if the service was registered without a realm

o  supportsRealm: aRealm
by default, answer true, if users are registered for a realm.
Redefine this, if you use your own user database.

o  usersForRealm: aRealm
by default, forward to my server. However, individual services might
redefine this to define their own, private user-groups

helpers
o  adjustReponseHeaderForWebSocketRequest: aRequest
empty -> no support of any extension at all,
be explicit by sending the empty extensions line
instead of sending no extensions line

initialize & release
o  initialize
(comment from inherited method)
just to ignore initialize to objects which do not need it

o  postStopServing
this is sent after the HTTPServer stops to accept connections
Can be redefined in subclasses for doing any actions

o  preStartServing
this is sent before the HTTPServer starts to accept connections
Can be redefined in subclasses for doing any actions

o  shutdown
invoked when deregistered, after the last request can be served.
Can be redefined in subclasses to perform service specific cleanup actions.

o  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
o  commonChangeFromRequest: aRequest
extracts parameter from an html-maintenance post-request
(common parameters, valid for all services)

o  commonInputFieldsForRequest: aRequest change: change
generates the html-fragment for maintenance form
(common fields, valid for all services)

o  specificChangeFromRequest: aRequest
extracts parameter from an html-maintenance post-request;
service specific - to be redefined by services.

o  specificInputFieldsForRequest: aRequest
generates the html-fragment for the maintenance form;
service specific - to be redefined by services.

printing
o  nameInSettingsTable
redefined in ComancheService, which adds the module-name

o  printOn: aStream
(comment from inherited method)
append a user printed representation of the receiver to aStream.
The format is suitable for a human - not meant to be read back.

The default here is to output the receiver's class name.
BUT: this method is heavily redefined for objects which
can print prettier.

queries
o  acceptsWebSocket: webSocket request: aRequest
subclasses should redefine this, to check for a concrete webSocket request
to be valid and allowed at this time

o  allowRobotsPaths
cg: who was it to name this method just the opposite of what it really does ?

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  allowWebSockets
subclasses should redefine this, to return true
(or initialize allowWebSockets to true),
if it is generally prepared for webSockets.
However, it still has to check incoming individual requests with acceptsWebSocket:

o  debugErrors
answer true, if we run in debug mode,
i.e., a debugger should be opened on error

o  forbiddenRobotsPaths
return the disallowed paths for robots

o  isRunning
answer true if service is running

o  overallNumberOfRequests
the overall number of incoming requests

queries-service
o  isAllowedInMaintenanceMode
return true, if this service is also allowed while the server is in maintenance mode

o  isFileService
anwser true, if this services serves files

o  isHTTPService
anwser true

o  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.
If the linkname was not explicitely assigned (via linkName: or linkNames:),
then the service's class is asked for a default linkNames

o  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.
If this is never called, then the service class is asked for a default name

o  linkNames
return the relative pathName of this service; i.e. if
'Bla' is returned, the service is reached as http://hostname:port/Bla.
If the linkname was not explicitely assigned (via linkName: or linkNames:),
then the service's class is asked for a default linkNames

o  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'.
If this is never called, then the service class is asked for a default name

o  nameInSettingsDialog

o  realm
return the realm - if non nil, the request must be authorized

o  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)

o  skipInstvarIndexInDeepCopy: anIndex
answer true, if the instance variable at: anIndex
should not be copied on #deepCopy

o  suppressInHomePage
answer true, if the service should not be visible in the server's home page

registration
o  addAuthentificationTo: aServer

o  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.

o  addStandardFileServicesTo: aServer
many services need the files in data/sampleServerDir/files.
This method registers a corresponding file service

o  isRegistered
answer true, if this service is registered with a server

o  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) **

o  registerServiceOn: anHTTPServer
register myself as service on a single HTTPServer

o  registerServiceOnPort: aPortNr
ensure that a webserver is running on aPortNr,
create a new service and register me as service reachable via my linkNames (the default servicePaths)
inside that webserver

o  release
(comment from inherited method)
remove all references to objects that may refer to self.
Subclasses may redefine this method but should do a 'super release'.

o  removeRequiredForeignServicesFrom: aServer

o  unRegister
unregister myself from my HTTPServer

o  unRegisterServiceIn: anHTTPServer

** This is an obsolete interface - do not use it (it may vanish in future versions) **

o  unRegisterServiceOn: anHTTPServer
unregister myself from an HTTPServer

request handling
o  _process: aRequest
internal processing method: care for synchronization

o  process: aRequest
all the work is done in this method.
Any service has to implement this method

** This method must be redefined in concrete classes (subclassResponsibility) **

o  processWebSocketRequest: aRequest
tell the client that the webSocket request has been accepted
to do this send a response header with a matching hash in #Sec-WebSocket-Accept

o  startServingWebSocket: webSocket
to be redefined in subclasses (services) which do handle webSockets;
close here, in case it was not redefined

** This method must be redefined in concrete classes (subclassResponsibility) **

settings persistency
o  elementDescriptorFor: anAspect
support for persistency:
answer the elements to be made persistent with an ObjectCoder

o  settingSelectors
answer the selectors that are used to configure a service - i.e. those which are
saved in the webServer-settings file.

Usage example(s): 

       HTTPService new settingSelectors

Private classes:

    NoRealmBehavior

ST/X 7.7.0.0; WebServer 1.702 at 20f6060372b9.unknown:8081; Thu, 21 Nov 2024 12:45:36 GMT