xmlStorageSystem

Updated: 10/15/01 DW, 12/1/01 DW, 12/11/01 DW, 3/9/02 DW, 4/1/02 JES.

xmlStorageSystem is an Internet storage system for XML documents that's programmable via XML-RPC and SOAP 1.1. This specification documents the system for SOAP 1.1, however the same procedures are also available in XML-RPC in UserLand's implementation.

xmlStorageSystem has entry-points that allow you to register with the service; upload a group of files (as few as 1); query the server to find out its capabilities; and to register a notification request.

The XML documents it stores are accessible through HTTP.

It allows callbacks for publish-and-subscribe.

xmlStorageSystem is the back-end for upstreaming in Radio 8. The server is implemented in Radio Community Server.

The xmlStorageSystem entry-points are documented in the following sections.

struct xmlStorageSystem.registerUser (email, name, password, clientPort, userAgent, serialNumber)

Creates a new account on the server, or updates an existing account.

email, a string, identifies a user.

name, a string, is the user's name.

password, a string, it's the user's password.

clientPort, a number, is the port the user's HTTP server is running on.

userAgent is a string that says what software is making the request.

serialNumber is a string that may be used by the server to enable or disable features for individual users.

You must call register before saving files or using other xmlStorageSystem functions.

As with all the entry points, register returns a struct. Look for the presence of flError, a boolean; if true, the operation didn't work, and message, a string, contains a human-readable explanation of the error.

struct xmlStorageSystem.saveMultipleFiles (email, password, relativepathList, fileTextList)

The core entry point in xmlStorageSystem.

email and password identify a user.

relativePathList is a array of strings, each of which identifies the location of the corresponding file in the fileTextList, relative to the top level of the user's HTTP-accessible directory. The path is slash-separated, and may or may not start with a slash. Example: test/clock2.xml.

fileTextList is an array of strings, containing the text to be stored in a file.

saveMultipleFiles returns a struct containing urlList, a array of HTTP urls corresponding to the files that were saved. If there was an error saving the file its url in urlList is the empty string. As with the other xmlStorageSystem calls, flError indicates if there was an error, and message provides human readable text, in English, explaining the error.

struct xmlStorageSystem.deleteMultipleFiles (email, password, relativepathList)

Follows the calling conventions of saveMultipleFiles, but of course the files are deleted not saved.

The returned struct contains an array of strings called errorList, corresponding to the elements of the relativePathList. If flError returns true, the error messages for the files that couldn't deleted are provided, in English.

struct xmlStorageSystem.getServerCapabilities (email, password)

Returns a struct containing:

1. legalFileExtensions, a array of file extensions that you may upload.

2. maxFileSize, a number, the maximum file size.

3. maxBytesPerUser, a number, the maximum number of bytes allowed per user.

4. ctBytesInUse, the number of bytes in use by the indicated user.

5. yourUpstreamFolderUrl, a string, the URL of the folder containing your files.

Other elements are continually added to this struct as we expand the capabilities of the community server and the desktop content management system.

struct xmlStorageSystem.getMyDirectory (email, password)

Deprecated. Not used by Radio 8.

Returns a struct that describes the contents of your folder.

It takes two parameters, email and password, just like the other routines, and it returns a struct containing information about each of the files. The name of each sub-struct is is file00001, file00002, etc.. Each sub-struct contains relativePath (a string), size (a number), whenCreated and whenLastUploaded, both date-times, and url, a string.

struct xmlStorageSystem.mailPasswordToUser (email)

email is a string that identifies a user. It must be an email address. (Other routines in this interface allow email to be an arbitrary string that identifies a user.)

The server searches its database looking for a user whose email address matches, and then sends the password for that user to the email address.

struct xmlStorageSystem.requestNotification (notifyProcedure, port, path, protocol, urlList, userinfo)

Registers a publish-subscribe notification request with the server.

requestNotification takes five parameters:

1. notifyProcedure, a string. The name of the procedure that the server should call to notify the workstation of changes,

2. port, a number, the TCP port the workstation is listening on.

3. path, a string, the path to its responder.

4. protocol, a string indicating which protocol to use (xml-rpc, soap or http-post, case-sensitive).

5. urlList, an array of urls of files to be watched. All the urls must be resources served by the server, and

6. userinfo, a struct containing application-specific information the client wants to pass to be stored on the server, associated with the user who is requesting notification. You may of course send an empty struct.

The server can determine the IP address of the caller from the request. A workstation cannot make a registration call on behalf of another.

When a subscribed-to resource changes the server calls back to the procedure named in the registration call with one parameter, the url of the resource that changed. At that point the workstation could read the resource, or notify other workstations that the resource has changed, clear a cache, send an email or do nothing. The workstation returns true.

By convention registrations expire after 25 hours. Workstations should register every 24 hours for each subscription to keep them current. (In the pub-sub world this is called a lease.)

For background see SOAP Meets RSS.

struct xmlStorageSystem.rssPleaseNotify (notifyProcedure, port, path, protocol, urlList)

Note 4/1/02 by JES: This procedure is now deprecated. It will continue to be supported, but for new implementations, please use xmlStorageSystem.requestNotification instead.

Registers a publish-subscribe notification request with the server.

pleaseNotify takes five parameters:

1. notifyProcedure, a string. The name of the procedure that the server should call to notify the workstation of changes,

2. port, a number, the TCP port the workstation is listening on.

3. path, a string, the path to its responder.

4. protocol, a string indicating which protocol to use (xml-rpc, soap or http-post, case-sensitive), and

5. urlList, an array of urls of files to be watched. All the urls must be resources served by the server.

The server can determine the IP address of the caller from the request. A workstation cannot make a registration call on behalf of another.

When a subscribed-to resource changes the server calls back to the procedure named in the registration call with one parameter, the url of the resource that changed. At that point the workstation could read the resource, or notify other workstations that the resource has changed, clear a cache, send an email or do nothing. The workstation returns true.

By convention registrations expire after 25 hours. Workstations should register every 24 hours for each subscription to keep them current. (In the pub-sub world this is called a lease.)

For background see SOAP Meets RSS.

struct xmlStorageSystem.ping (email, password, status, clientPort, userinfo)

email and password are strings that identify a user.

status is a number. If 0, the client is just telling the server that it's still connected. If 1, the client is telling the server that it is about to disconnect. All other values are reserved.

clientPort, a number, is the port the user's HTTP server is running on.

userinfo is a struct containing application-specific information the client wants to pass to be stored on the server, associated with this user. You may of course send an empty struct.

Synchronizing with directory.opml 

Deprecated. Not used by Radio 8.

There's a special file called directory.opml, at the top level of your directory. When you upload this file, xmlStorageSystem makes sure that the contents of your directory agrees with the contents of the file.

Here's an example of a directory.opml file, see the OPML specification for more information on this format.

You can also synchronize in the other direction, by reading directory.opml, and downloading the files that have changed through HTTP, and deleting files in the local version that are not in the directory.

Glue for Frontier or Radio 

Frontier.root or Radio.root both have support for xmlStorageSystem baked in. Jump to system.verbs.apps.xmlStorageSystem. Docs are here.

Philosophy 

It's our philosophy to document all interfaces between our products and to use open and discoverable formats that are as simple as they possibly can be. We are against lock-in, and feel that our customers can choose among many competitive products and still find their way to the best solution, which in many cases, will be UserLand's. No software company can be everything to everybody.

Update: 4/7/01 

Added getMyDirectory.

Update: 4/8/01 

Added example wire dumps.

Update: 10/15/01 

Many of the routines take a parameter named email. Implementors may use email addresses to identify users. However, to interop with other xmlStorageSystem applications, you must not assume that it is an email address. Since SOAP uses named parameters, changing the name of these parameters to something more neutral like "userid" would break applications.

xmlStorageSystem.registerUser has a new parameter, serialNumber. It is an optional parameter in UserLand's server implementation. New versions of UserLand clients will always pass a serialNumber parameter. If the user does not have a serial number it passes the empty string.

xmlStorageSystem.ping is a new procedure.

In the introductory text, made it clear that while this spec appears on SoapWare.Org, the spec also has been implemented in XML-RPC.

Update: 12/1/01 

Added xmlStorageSystem.mailPasswordToUser.

Update: 12/11/01 

Added xmlStorageSystem.deleteMultipleFiles.

Update: 3/9/02 

Brought spec current with the Radio Community Server 1.0.

1. No longer request that registerUser be called on startup. It should only be called to actually register a new user.

2. Deprecated getMyDirectory. It's not used by Radio 8.

3. Deprecated directory.opml. It's not used by Radio 8, and is optional in Radio Community Server, defaults off. Changed the example to point to a file that's currently maintained.

4. The struct returned by getServerCapabilities gets new elements as the features of the community are expanded.

5. Deleted section describing UserLand's xmlStorageSystem server. The server it described is not running the current software.

6. Updated the philosophy. We welcome competition.

Update: 4/1/02 

Added xmlStorageSystem.requestNotification. This procedure replaces xmlStorageSystem.pleaseNotify, which is now deprecated.