| |
Table of Contents |
Note: This feature is available only with VolanoChatPro.
The database support allows you to integrate the information in an existing or new member database with one or more VolanoChatPro servers in the following ways:
The database need not reside on the same machine as the VolanoChatPro server. It can provide a central directory for several VolanoChatPro servers, as shown in the figure below.
Figure 1: Centralized member database.
If you do not have a database, you can get a full featured Structured Query Language (SQL) database for free from T.c.X. DataKonsultAB, called MySQL. MySQL supports many different programming interfaces, including:
You provide the information from your database to the VolanoChat server through three simple CGI scripts. The scripts are invoked by a Uniform Resource Locator (URL) you define to the VolanoChatPro server. The scripts can be implemented in any language and architecture supported by your Web server and your database. You can even write the scripts in Java as a Java servlet and add them to VolanoChat's built-in servlet runner. The three scripts, and the names of the properties that define their addresses, are:
member.accessmember.namemember.documentBoth member.access and member.name are VolanoChat server properties (defined in properties.txt), while member.document is a VolanoChat applet property (defined in english.txt by default).
The member.version server property value determines the format of the access and name script responses. If the version property is set to 2.1, the CGI script returns up to three lines of text in a format shown for each script below. Any other value (including no value) indicates the scripts return the version 2.0 XML format described below.
The member access script is invoked when members enter their name and password into the member interface of the VolanoChat applet. It is invoked as a normal HTTP GET request, and its response determines whether the VolanoChatPro server grants access to the member.
The access script is defined by the URL you specify with the member.access server property. The VolanoChatPro server drops in the member name and password which the visitor entered on the VolanoChat member applet. For example, you might define a script with a format as follows:
member.access=http://red.volano.com/member?name={0}&password={1}
The VolanoChatPro server fills in this URL template such that:
When the member.version property is not equal to 2.1, the member access script returns an XML document with a single root element of the form:
<result value="[true|false|error]"> Profile text or error message. </result>
If the member name and password are valid, the access script returns a result of true along with the optional member profile string. For example:
<result value="true"> This is the member's profile. </result>
If the member name is not found or the password is not valid, the access script returns a result of false. For example:
<result value="false"> </result>
If an error occurs processing the request, the access script returns a result of error along with an optional descriptive error message. For example:
<result value="error"> Unable to connect to database. </result>
Below is a link to a sample version 2.0 member access Java servlet. This sample does not access a real database, so you would have to modify it in order to access your own membership database:
member.access 2.0 scriptWhen the member.version property is set equal to 2.1, the member access script returns from zero to three lines of text of the form:
true|false|error Profile text or error message. true|false
The first line returns true if the name and password are correct, false if the name and password are not correct, and error if an error occurred accessing the database. The second line returns the member's profile string or an optional error message. The third line returns true if the member has a Web page for access through the member.document script and false if no link should be displayed for a member Web page.
If no content is returned in the response, the default response is assumed to be:
false
If the member name and password are valid and the member has a Web page, the access script returns a result of true, the optional member profile string, and true for the Web page link. For example:
true This is the member's profile. true
If the member name is not found or the password is not valid, the access script returns a result of false. For example:
false
If an error occurs processing the request, the access script returns a result of error along with an optional descriptive error message. For example:
error Unable to connect to database.
Below is a link to a sample version 2.1 member access Java servlet. This sample does not access a real database, so you would have to modify it in order to access your own membership database:
member.access 2.1 scriptThe member name script is invoked each time someone enters a chat room. It is invoked as a normal HTTP GET request, and its response determines whether the visitor may enter the chat room with the chosen name. This script implements name reservation for your members.
The access script is defined by the URL you specify with the member.name server property. The VolanoChatPro server drops in the member name which the visitor entered on the main chat window as the nickname for entering the room. For example, you might define a script with a format as follows:
member.name=http://red.volano.com/taken?name={0}
The VolanoChatPro server fills in this URL template such that:
When the member.version property is not equal to 2.1, the member name script returns an XML document with a single root element of the form:
<result value="[true|false|error]"> Optional error message. </result>
If the nickname is taken by a member, the name script returns a result of true. For example:
<result value="true"> </result>
If the nickname is not taken by a member, the name script returns a result of false. For example:
<result value="false"> </result>
If an error occurs processing the request, the name script returns a result of error along with an optional descriptive error message. For example:
<result value="error"> Unable to connect to database. </result>
Below is a link to a sample version 2.0 member name Java servlet. This sample does not access a real database, so you would have to modify it in order to access your own membership database:
member.name 2.0 scriptWhen the member.version property is set equal to 2.1, the member name script returns from zero to two lines of text of the form:
true|false|error Optional error message.
If the nickname is taken by a member, the name script returns a result of true. For example:
true
If the nickname is not taken by a member, the name script returns a result of false. For example:
false
If an error occurs processing the request, the name script returns a result of error along with an optional descriptive error message. For example:
error Unable to connect to database.
Below is a link to a sample version 2.1 member name Java servlet. This sample does not access a real database, so you would have to modify it in order to access your own membership database:
member.name 2.1 scriptThe member document script is invoked when a visitor clicks on the member profile link which may be prefixed to each member's profile in the chat rooms. It is invoked as a normal HTTP GET request, and it should return the Web page associated with the member.
The access script is defined by the URL you specify with the member.document VolanoChat applet property. The VolanoChat applet drops in the member's nickname and the nickname of the person requesting the page, if available. For example, you might define a script with a format as follows:
member.document=http://red.volano.com/page?for=%0&by=%1
Note that the server member.access and member.name properties use the Java 1.1 notation of "{n}" for substitution variables, while this member.document applet property uses the Java 1.0.2 notation of "%n".
The VolanoChat applet fills in this URL template such that:
The requestor's nickname is available if the requestor is clicking the link in a chat room or is also a member. The nickname is unavailable if the requestor is not a member and is clicking the link from the main chat panel outside any chat room. Members will always have their name filled in the %1 variable, whether they've entered a room or not.
Below is a link to a sample member document Java servlet. This sample does not access a real database, so you would have to modify it in order to access your own membership database:
member.document scriptMake sure to set the content type of the server script responses to plain text by adding the following header to your member.access and member.name script responses:
Content-type: text/plain
You should send back the HTML response document of the member.document script as HTML text with:
Content-type: text/html
You can improve the performance of the member access and name scripts by making sure to enable HTTP keep-alive support in their responses. See the Apache Keep-Alive Support page, or the corresponding documentation for your own Web server, for additional information.
As with any HTTP GET request, the nickname and password variables are URL encoded before being sent. So "John Smith" is sent as either "John+Smith" or "John%20Smith", and a password string such as "tes/ting" is sent as "tes%2Fting". Most CGI script libraries have simple routines for decoding the variables from their URL encoded form into their original values. Note that it is the responsibility of the member access, name, and document scripts to decide whether things such as upper and lower case are important.
When forming the XML response document in the version 2.0 format, you need to put the tags exactly as shown in the examples above, although you may also put the result on one line as follows:
<result value="false"></result>
or put the profile text or error message on multiple lines as follows:
<result value="true"> This is the profile. </result>
In the latter case, you'll get the single line "This is the profile." for the profile.
| |
XHTML 1.0 | Table of Contents |