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
      |
      +--HTTPSelectorService
      |
      +--HTTPTentativeObjectService
      |
      +--SeasideService

Package:
stx:goodies/webServer
Category:
Net-Communication-HTTP-Services
Version:
rev: 1.194 date: 2017/02/21 13:57:11
user: mawalch
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
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  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 raises an error - it must be redefined in concrete classes **

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

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

o  isBrowserStartable

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  linkNames
return a collection of default paths (with initial slashes).
Either redefine this in a concrete service, or #linkName (for a single default linkName).

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  unRegisterServiceIn: anHTTPServer

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  contextForRequest: aRequest

o  httpServer

o  httpServer: something

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

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

queries
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  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  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: aServer
register myself as service on a single HTTPServer

o  release

o  removeRequiredForeignServicesFrom: aServer

o  unRegister
unregister myself from my HTTPServer

o  unRegisterServiceIn: anHTTPServer

o  unRegisterServiceOn: aServer
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 raises an error - it must be redefined in concrete classes **

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.1.0.0; WebServer 1.663 at exept.de:8081; Fri, 22 Mar 2019 10:06:09 GMT