Moto - The Native Web Programming Language

7 Interacting with Apache

Both the moto module, and any of your own moto applications that you compile with mmc, run as dynamically loaded modules within the apache webserver. Thus they may be configured by modifying the httpd.conf file, they access HTTP Requests and Responses , they can parse HTTP headers and form submissions for cookies and file upload, via included APIs. To make use of these APIs from within your moto pages you must

$use("codex.http")

7.1 Configuring Modules

Both the moto module, and any moto application compiled with mmc, may be configured in your httpd.conf . Basic configuration of your httpd.conf is necessary just to load the moto module:

LoadModule moto_module libexec/mod_moto.so
AddHandler moto .moto

Or to load a compiled moto module

LoadModule histoexam_module libexec/mod_histoexam.so
<IfModule mod_histoexam.c>
   <Location /histoexam1>
       SetHandler histoexam
       HistoexamOption Location /histoexam1
   </Location>
</IfModule>

In the above example there is an Apache directive you probably haven't seen before

HistoexamOption Location /histoexam1

All compiled modules get a new directive that can be used to pass configuration information into the module. The directive is {Module Name (with the first letter capitalized)} + 'Option' (hereafter reffered to as ModOption) . Using a ModOption directive you can pass arbitrary configuration parameters into your module. In the above example the parameter 'Location' is being set. This parameter is present in all compiled moto modules and allows for them to be relocated elsewhere in your website. You can use ModOptions to set an arbitrary number of different parameters and just like other Apache directives, parameters nested within Location or Directory blocks take precendence over those outside and apply only inside those Directory or Location blocks.

<IfModule mod_iolio.c>
  IolioOption SharedHeapSize 128M
  <Location /iolio2 >
     SetHandler iolio
     IolioOption Location /iolio2
     IolioOption DBName iolio1
     IolioOption DBUser maka
     IolioOption DBPassword shlaka
  </Location>

  <Location /iolio3 >
     SetHandler iolio
     IolioOption Location /iolio3
     IolioOption DBName iolio2
     IolioOption DBUser foo
     IolioOption DBPassword bar
  </Location>
</IfModule>

To set parameters for the moto module (or for your application while it's still in development) use the directive 'MotoOption'.

<IfModule mod_moto.c>
  MotoOption SharedHeapSize 128M
  MotoOption SignalsThrowExceptions true
  AddHandler moto .moto

  <Location /iolio >
     MotoOption DBName iolio
     MotoOption DBUser root
     MotoOption DBPassword macamaca
  </Location>
</IfModule>

To access options set through this mechanism in your moto application use the function getConfigOption().

$* Set up the database connection *$

$declare(MySQLConnection conn = new MySQLConnection(
  "",
  getConfigOption("DBName"),
  getConfigOption("DBUser"),
  getConfigOption("DBPassword")
))

What follows is a list of configuration options that are built in to either the moto module or compiled modules

Directive Valid For Scope Description
Location mmc compiled modules location or directory block Sets the path prefix that pages within the compiled moto directory expect prior to the page name in the URL
SharedHeapSize mod_moto and mmc compiled modules global Sets the size of the shared heap.
SignalsThrowExceptions mod_moto and mmc compiled modules global Catches SIGSEGV and SIGBUS if raised during page interpretation and re-throws them as exceptions.
MXPath mod_moto global Lets you specify the paths that the moto interpreter will search for moto extensions. The value should be a ':' delimited list of paths.
LockDir mod_moto and mmc compiled modules global Lets you specify the directory that the .lock files used for concurrency control by the memory manager and context will be dropped off (the default is /tmp)
Session.Disable mod_moto and mmc compiled modules location or directory block Lets you turn off session tracking for location in which the directive applies.
Session.SetSSIDCookie mod_moto and mmc compiled modules location or directory block Lets you identify the current session via a cookie stored on the client browser. If the sid state variable is also present than the session identified by the sid state variable takes precedence.
Session.MatchSSIDCookie mod_moto and mmc compiled modules location or directory block If the sid state variable is also present in the URL then both sid and the ssid must agree thus providing a limited defense against 'session hijacking'. This option is only usefull in combination with the Session.SetSSIDCookie option.
Session.MatchClientIP mod_moto and mmc compiled modules location or directory block Including this option means that all requests for a given session must come from the same IP address that started the session thus providing a limited defense against 'session hijacking'.
Session.Timeout mod_moto and mmc compiled modules global Specifies the number of seconds of inactivity before a session will be 'timed-out'.

7.2 Inspecting the HTTP Request

Moto currently has basic support for letting you inspect the HTTPRequest. You get the request by calling the getRequest() function defined in codex.http. Once you have it you can call a variety of methods on it.

Method Description

String getHostname() Returns the hostname of the requested URL
String getURI() Returns the path part of the URL (after the host name but before the ?)
String getFileName() Returns the full path on disk of the reuested page
String getMethod() Returns the method by which the page was requested e.g. "POST" or "GET"
String getProtocol() Returns the protocol by which the page was requested e.g. "HTTP/1.1"
String getHeader(String header) Returns the value of the specified header e.g. getRequest().getHeader("User-agent") might return "Mozilla/4.5 (compatible; OmniWeb/4.1-beta-1; Mac_PowerPC)"
Cookie getCookie(String name) Returns the Client Side cookie with the specified name
Enumeration getCookies() Returns an enumeration of all the cookies that were parsed from the HTTPRequest
Enumeration getMIMEParts() Returns an enumeration of all the 'MIMEEntity's submitted to this page. Mime parts get submitted on file upload forms (or any form with enctype="multipart/form-data")
MIMEEntity getMIMEPart(String name) Returns the MIME part with the specified name. Mime parts get submitted on file upload forms. This function can be dangerous if you've specified a form with two fields named the same. This function will get you the first one only.

7.3 Getting and Setting Cookies

Moto supports the setting and retrieval of client side cookies. You can set a cookie by creating a new cookie object, setting the required fields, and finally calling setCookie on the HTTPResponse.

$declare(Cookie cookie = new Cookie())

$do(cookie.setName("maka"))
$do(cookie.setValue("shlaka"))
$do(cookie.setVersion("1"))

$declare(HTTPResponse res = getResponse())
$do(res.setCookie(cookie))

Once set, you may retrieve a cookie by name on subsequent pages views by calling the getCookie() method on the HTTPRequest object, or you can enumerate through all the cookies the client submitted via the getCookies() method

$declare(Enumeration cookies = getRequest().getCookies())
$while(cookies.hasNext())
$declare(Cookie cur = <Cookie>cookies.next())
<li>Got cookie: $(cur.toString())
$endwhile

With a cookie in hand you can inspect any of it's relevant fields (though only version,path and domain may get set when a cookie is transmitted from the browser back to the server

<pre>
Cookie Name      : $(cookie.getName())
Cookie Value     : $(cookie.getValue())
Cookie Domain    : $(cookie.getDomain())
Cookie Version   : $(cookie.getVersion())
Cookie Path      : $(cookie.getPath())
Cookie Comment   : $(cookie.getComment())
Is Cookie Secure : $(cookie.isSecure())

Cookie : $(cookie.toString())
</pre>

7.4 Multipart MIME Support

When users submit a form with enctype="multipart/form-data" they are actually submitting a multipart mime message to the webserver.

By filling the form input field with type=file, a user can upload a file to a webserver. This file may then be parsed out of the HTTPRequest on the next page. It's contents will be maide available to the moto page in a MIMEPart named with whatever name the form field was given.

  $if(getRequest().getMIMEPart("uploaded_file") != null &&
      getRequest().getMIMEPart("uploaded_file").getBodyLength() > 0)
     $do(
        putFileBytes(
           "/usr/local/wa/dhakim/httpd/htdocs/foo.gif",
           getRequest().getMIMEPart("uploaded_file").getBody(),
           getRequest().getMIMEPart("uploaded_file").getBodyLength()
        )
     )
  $endif

It's possible to present users with multiple file upload or other form fields. These will all be submitted as MIME parts. You can iterate over all submitted mime parts using the getMIMEParts() method of HTTPRequest. You can also inspect the mime headers associated with each part.

  Parts Sent:
  <ul>
     $declare(Enumeration parts = getRequest().getMIMEParts())
     $while(parts.hasNext())
        $declare(MIMEEntity curPart = <MIMEEntity>parts.next())
        <li>$(curPart.getName())
        <ul>
            <li><b>filename</b> : $(curPart.getFileName())
            <li><b>content type</b> : $(curPart.getContentType())
            <li><b>content transfer encoding</b> : $(curPart.getContentTransferEncoding())
            <li><b>body length</b> : $(curPart.getBodyLength())
        </ul>
     $endwhile
  </ul>

Regular forms (forms without the enctype set to multipart/form-data) do not submit their contents as multipart mime messages. An explanation of how values sent through those forms are retrieved is dealt with in the following section on state management.