The APL+WebServices - Desktop version 1.5 (beta) now includes wildcards for virtual paths and support in custom-errors for virtual paths as well.
This means that a virtual path can be used in reasonably interesting configurations.
A wildcard path (or "wildpath") is defined when the virtual path ends with a "*". Any request-uri that begins with a wildcard path will be accepted and processed by the related wsid.
Publishing static and dynamic files:
If you want to publish static files, such as images, which reside in a directory not under your public http directory, you could set up a wildpath similar to:
In our case we are going to call a function named ReturnFile:
Set your right argument to be:
Which will pass the requested uri to the function ReturnFile.
Then set the result of the ReturnFile function to be:
Which indicates that ReturnFile is going to return a four element array with the filename in the first element, similar to:
C:\test\file\picture.gif
The second element of the array will be a numeric 0 indicating that we do not want the server to delete the file after it is returned to the client.
The third element would be the status-code. When the file requested exists this would be a numeric 200, when the file did not exist, this would be a numeric 404. In the event you were also checking the other header values for access, the status-code could be set to an appropriate response.
The fourth element of the array is the reason for the status code. For instance in case of success it would be "OK", in the event of a file not found, it could be "File not found" . This is arbitrary text, but these are the typical values used.
The function could look something like this:
’ r„ReturnFile url;filepath
[1]
[2] © Since we know that /images/ is our virtual path, this function
[3] © was called because /images/ is the beginning of our url.
[4] © So we can delete this from the url.
[5]
[6] url„8‡url
[7]
[8] © This will remove /images/ and leave the file name or perhaps the
[9] © file name and a path.
[10] © If we anticipate a path then we need to change the /'s to \'s
[11]
[12] (url='/')„'\'
[13]
[14] filepath„'c:\mypersonal\images\'
[15]
[16] :if FileExists filepath,url
[17] r„(filepath,url) 0 200 "OK"
[18] :else
[19] r„'c:\myerrorpages\404.htm' 0 404 "File not found"
[20] :endif
[21]
[22]
’
That is all that is needed to map a virtual path to any other directory or directories.
It is quite easy to enhance this function to make decisions based on the url which would in turn influence which files were returned.
If we want to return a file which is created programmatically instead of a static file, all we need to do is create the information to be returned, say in the data variable, and then do this:
file„GetUniqueFileName
file Œxntie ¯100
data Œnappend ¯100
file Œnuntie ¯100
r„file 1 200 "OK"
The server will then return the file to the client and delete the file at the end of the transaction.
If you are doing a more complex return involving for example excel spreadsheet files, you would want to add the content-type parameter to the return, say as the fifth element in the array, and set it to: application/octet-stream
The browser will automatically display the spreadsheet in the browser using excel.
If you really want to provide the user with the option of either having the spreadsheet automatically displayed in the browser or saved to disk, you would want to add a sixth element to your return, which is content-disposition which you would set to:
attachment: filename=yourfilename.xls
This would cause the "open/save as" dialog to pop up, and the name you specified in the content-disposition to be displayed as the name of the file to be saved.
So, you can see that by adding a couple of parameters to the return you can dramatically enhance and control what you return to the user.
Wildpaths and Data
When a wildpath is part of a GET with data, or a POST, the server will accept the url, process the data parameters and then call the appropriate wsid and function.
For instance, we could have a function which does math, such as:
’ r„url MATH inp;a;b
[1] (a b)„2†inp
[2]
[3] 'a'
[4] a
[5] 'b'
[6] b
[7] url„(¯1+url¼'?')†url
[8] url„Lcase ¹¯1†(url¬'\')›url
[9] :select url
[10] :case 'add'
[11] r„a+b
[12] :case 'mult'
[13] r„a×b
[14] :case 'div'
[15] r„a÷b
[16] :case 'subtract'
[17] r„a-b
[18] :else
[19] r„0
[20] :endselect
’
The virtual path could be:
The right arguments could be:
The server will take the value pairs submitted and create the right argument to the function with "a" set to the associated integer value, with "b" set also.
The left argument could be:
This will provide the MATH function the url being requested by the client.
The return from the function could be:
In this case we are expecting an integer reply, and the server will change the returned integer into the appropriate webservice xml.
In our example the client could enter:
http://www.yourserver.com/test/math/add?a=10&b=20
The client would see in their browser:
- 30
If they were to enter:
http://www.yourserver.com/test/math/add?a=10&b=20&a=30&b=30
The client would see in their browser:
- 30 60
Because APL does arrays naturally. Keep in mind that our simple example function does not deal with data checking or error handling, but the concept is there.
In fact if they were to enter:
http://www.yourserver.com/test/math/something/else/add?a=10&b=20&a=30&b=30
The result would still work.
The opportunities presented by wildpaths is quite exciting. Whether you are using a simple GET to return a file, or do dynamic calculations, the wildpaths can dramatically reduce the work required to produce a dynamic interactive website which is easy to maintain over time.
Setting Custom Error to either a VirtualPath or a WildPath
The custom error tab in the webserver properties dialog provide the ability to determine what is returned for the different possible errors which can occur.
The most common error is page not found. This has a status code of 404.
Using the custom error tab you can set the server to return either a static file or to return the result of a virtual path or a wildpath.
This means that whenever a user submits a url which does not exist on your site, the server will call the specified function and wsid associated with the virtual path or wildpath chosen for that custom error.
This could be used to either return a more intelligent "file not found page", or to actually return valid pages based on the url submitted.
The url that would be passed to the function would be the original url submitted by the user, not the virtual or wild path.