This document describes the fundamental steps required by the XLiRAD AppServer administrator to properly setup the XLiRAD Server for first use. The steps will configure the AppServer to integrate with the existing webserver and servlet manager as well as establish the basic network settings, database connections, email addresses, etc. to ensure the proper working of the server in its environment.
Upon first use, the administrator will enter the password for the server and a confirmation match to ensure that the password was correctly entered. This password will be asked for at startup and to unlock the running server if it has been locked by the administrator. The password can be changed later by using the user management dialog boxes.
Before downloading the XLiRAD AppServer, the buyer should have received an email with the proper customer id number and a license key. After the first use, when the id is entered, the server will remember the id for future uses.
Before downloading the XLiRAD AppServer, the buyer should have received an email with the proper customer id number and a license key. After the first use, when the license key is entered, the server will remember the key for future uses. This key when combined with the customer id number guarantees the uniqueness of this XLiRAD AppServer on the network. Sharing of the customer id and the license key amongst multiple XLiRAD Servers is not allowed and will invalidate the License Key.
XLiRAD comes with the ability to auto-configure itself under most common scenarios. Most likely your configuration is on this list; if it is not, go to the section "None of these Connectors Matches my Configuration." You will see the following connectors available for installation under the "Connectors" menu heading of the XLiRAD AppServer.
Step 1) Select the Apache "conf" directory with the file chooser. XLiRAD will look for the configuration files that it needs to modify in the jserv subdirectory in the "conf" directory. If XLiRAD does not find the jserv subdirectory, then you do not have JServ currently installed with Apache and you need to do that first.
Step 2) Choose to install the XLiRAD Servlet in an existing zone, or choose to have XLiRAD create a new zone for itself.
Step 3) The XLiRAD Servlet is called "FormProcessor." If you wish to call it by another name from the URL line, choose to create a servlet alias with the more desirable link name.
Step 4) Press the "Install Connector" button to install the connector. You will need to restart Apache and Jserv before the first call to the "FormProcessor" servlet.
Step 1) Select the iPlanet installation directory with the file chooser. XLiRAD will look for named iPlanet servers in that directory.
Step 2) Select the iPlanet server that you wish to install the XLiRAD servlet "FormProcessor" into from the ComboBox.
Step 3) The XLiRAD Servlet is called "FormProcessor." If you wish to call it by another name from the URL line, choose to create a servlet alias with the more desirable link name.
Step 4) Press the "Install Connector" button to install the connector. You will need to restart the iPlanet Webserver before the first call to the "FormProcessor" servlet.
Step 1) Select the JRun installation directory with the file chooser.
Step 2) The XLiRAD Servlet is called "FormProcessor." If you wish to call it by another name from the URL line, choose to create a servlet alias with the more desirable link name.
Step 3) Press the "Install Connector" button to install the connector. You will need to restart JRun and the Webserver before the first call to the "FormProcessor" servlet.
Step 1) Select the "ServletExec ISAPI" subdirectory one level down from the ServletExec installation directory.
Step 2) The XLiRAD Servlet is called "FormProcessor." If you wish to call it by another name from the URL line, choose to create a servlet alias with the more desirable link name.
Step 3) Press the "Install Connector" button to install the connector. You will need to restart ServletExec and the Webserver before the first call to the "FormProcessor" servlet. Sometimes this connector requires a full box reboot in order to finish properly.
If none of the previous connectors match your configuration, then you will need to manually add classpath and servlet alias information to your Servlet Manager.
Step 1) Classpath. Add the following entries to your Servlet Manager's classpath:
<XLiRAD Installation
Directory>/classes
<XLiRAD Installation
Directory>/classes/XLiRAD.jar
<XLiRAD Installation
Directory>/beans
<XLiRAD Installation
Directory>/classes/US_export_policy.jar
<XLiRAD Installation
Directory>/classes/email.jar
<XLiRAD Installation
Directory>/classes/jce1_2_1.jar
<XLiRAD Installation
Directory>/classes/local_policy.jar
<XLiRAD Installation
Directory>/classes/sunjce_provider.jar
<XLiRAD Installation
Directory>/classes/xalan.jar
<XLiRAD Installation
Directory>/classes/xerces.jar
<XLiRAD Installation
Directory>/classes/xml.jar
<XLiRAD Installation
Directory>/classes/jcert.jar
<XLiRAD Installation
Directory>/classes/jnet.jar
<XLiRAD Installation
Directory>/classes/jsse.jar
Step 2) Servlet Alias. The XLiRAD servlet is called "FormProcessor." Create the appropriate aliases to called by other names from the URL line.
Step 3) Initialization Arguments. "FormProcessor" and its corresponding aliases need a servlet initarg with the following composition:
serverdirectory=<XLiRAD
Installation Directory>
Step 4) Most likely you will need to restart both your Servlet Manager and your Webserver.
An XLiRAD user is a developer that uses the remote XLiRAD client tools to do web development. An XLiRAD user is also a web client that has access to XLiRAD templates designated as "Administrative." The XLiRAD user's username and password will provide access to these realmed off templates.
Select the "User Management" menu item under "Configuration." In the "New User" group box enter a username, password, and confirmation, and press the "Add User" button. The user you have just created needs to be added to one or more groups to access XLiRAD functionality. This is covered in the next section.
Select the "User Management" menu item under "Configuration." Select the proper "Current User" and enter a new password and confirmation. Press the "Change Password" button to update the password.
Select the "User Management" menu item under "Configuration." Select the proper "Current User" and press the "Delete User" button. This immediately removes all privileges for that user.
XLiRAD is designed around the principle of functionality encapsulation. Groups are used to separate users and development into localizations such that no crossover takes place. In a consulting company, groups would most likely be used to separate projects. In the ASP model, groups would generally represent business clients using the ASP's services.
During the initial run, XLiRAD creates the "administrators" group with a single member, "administrator." This group has a default SQL Range of 1-500. For a description of SQL Ranges, see the next section
All database interactions in XLiRAD use SQL statements crafted by the developers. These SQL statements are numerically ordered in XLiRAD. A SQL Range is the range of consecutive indices that a group owns in which it can store its SQL statements. The SQL Range can be used to dictate the size of a project and is also used to group the SQL statements into logical divisions by XLiRAD group.
Select the "Group Management" menu item under "Configuration." In the "New Group" section, choose a name for the group, the start of the SQL Range, and the end of the SQL Range. Press the "Add Group" button to enable this new group. XLiRAD will validate that the specified SQL Range does not conflict with the range of an existing group. The SQL Ranges for all of the groups are visible and can be edited using the table in the bottom left corner of this screen and by pressing the "Update SQL Ranges" button.
Select the "Group Management" menu item under "Configuration." Select the proper "Current Group" and look at the "Members" and "Available Users" boxes below. Use the right arrow to remove the highlighted member from the group. Use the left arrow to add the highlighted available user to the group.
The basic XLiRAD Server Configuration discussed in this section is accessible through the "Server Setup" menu item under the "Configuration" menu.
XLiRAD uses JDBC drivers to make persistant connections to databases in order for XLiRAD templates to easily perform database operations: add, change, delete, etc. The XLiRAD administrator sets up these connections in advance and they are kept in a shareable pool for web requests to use. The connections are refreshed every half hour to ensure that they do not get stale and auto-disconnect.
Press the "Add Connection" button on the "Server Configuration" screen to access the add connection dialog. Depending on the database that you are accessing, some of the fields discussed below will not be necessary.
For JDBC-ODBC Bridge connections using an existing ODBC datasource, this field represents the name of the ODBC datasource. For non-ODBC connections, this field represents the name of the database inside the RDMS.
Choose the proper connection type that matches the desired target database.
XLiRAD determines its billing based upon the number of database connections purchased. This amount caps the total number of persistent connections available to your datasources. The default license size is 5 connections. Specify the number of connections, out of your licensed amount, that you wish to use for this datasource.
These fields are only used by non-ODBC based connections. Enter the URL/IP Address for the machine hosting the database and the listener port that the database uses for client requests.
These fields may or may not be necessary depending on your target database or connection type. Some ODBC connections store the username and password in the connection and do not require them here. Some experimentation may be necessary here to properly send the username and password to the database for validation. In most cases, entering them here, even if redundant with ODBC settings, should be acceptable by the database access validation system.
Database connection access is restricted by group. This prevents unauthorized XLiRAD users from other groups accessing, modifying database information or viewing database schemas from the SQLEditor client tool. More than one group can have access to a connection however if allowed by the administrator. XLiRAD Templates created by members of other groups cannot execute SQL Statements on a database not accessible by that group. This realming of database connections is designed specifically for the ASP model where different groups represent different companies that should have absolutely no access to each others data.
XLiRAD must have an open port assigned to it in order to listen for client requests. For XLiRAD Developers to use the client tools to access the server, they must have access from their client machines to the port on the server machine. If firewalls are in place, a hole may need to be poked in it for this port in order to allow XLiRAD Developers to work off site. All client requests to the server are encrypted; the hole in the firewall should not pose a security risk. The XLiRAD administrator must inform the client developers of this port so that they can connect to the server.
XLiRAD comes packaged with a servlet called "FormProcessor" that communicates between the webserver and the XLiRAD AppServer. If the administrator has used a "Connector" provided by XLiRAD, then this servlet alias should already be set. If the administrator manually configured the webserver or servlet manager, then the servlet alias chosen to access "FormProcessor" must be set. For example, if the servlet invoker is "/servlet" and the alias for "FormProcessor" is "engine," then the servlet alias should be entered as "/servlet/engine." Under the same scenario, but with no servlet alias created, the servlet alias should be entered as "/servlet/FormProcessor." XLiRAD needs to know how to call itself when auto-generating links from SQL Statements in HTML Tables, etc. This field should contain the relative URL that is used to access the XLiRAD servlet "FormProcessor."
This option tells the server to automatically connect to its database connections and start its port listener when the program is started. It also bypasses the login screen and logs in as the administrator. As a security measure, this option locks the server upon startup such that no settings are available for viewing or changing until the administrator has unlocked the server. This option is intended for use when the server is not local and the administrator does not have access the the server's user interfaces. If the box needs to be rebooted, etc., the administrator can easily telnet into the machine to start XLiRAD without needing access to the GUIs. This also allows XLiRAD to be placed in startup scripts; this is, however, difficult to do because the timing of connecting to the database and creating the port listeners must be precise in relationship to the starting of the database and the initialization of the ethernet card. In practicality, placing XLiRAD in startup scripts in only for the expert UNIX administrator and will require a lot of experimentation.
The XLiRAD AppServer is configurable to send error emails to the system administrator for corrective actions. Configure the email settings using the "Administrative Email" menu item under the "Configuration" menu.
XLiRAD needs to know the mail server to use in order to send administrative emails as well as the administrator's email address. By setting these fields and by pressing "Submit," the administrator will receive an email whenever an error occurs.
The administrator only receives emails that represent some sort of server failure. There are currently three serious failures that can occur:
1) XLiRAD constantly pings its listener port to make sure that it is still active. If the listener port fails to respond for any reason, XLiRAD will restart its listener and email the administrator of the failure. This is usually indicative of a network failure of some kind.
2) Every half hour, XLiRAD refreshes its database connections. If a connection refresh fails for any reason, that connection is unavailable for the next half hour. If this occurs, the administrator will be notified via email. This problem indicates either a network error or a database listener error.
3) If replication is in use between multiple XLiRAD Servers, SQL transactions are sent from the requested box to its replication targets. If the replication target is unavailable to receive its replication transaction, the administrator is emailed of the error. This indicates either a network error or that perhaps the target server is not currently running.
XLiRAD comes pre-packaged with a fully functional chat server. It is intended to allow XLiRAD developers to freely chat about their development and work together.
XLiRAD developers logged in to the XLiRAD Server through the client tool, TemplateMaker, can use the chat server. The Chat Server is realmed off by group to allow private conversations amongst developers in a certain group without giving information to another group's developers. In fact, the group chatters are completely unaware that any other groups exist, much less that they are also chatting on this server.
The chat server is intented for use in shops where the development team is not in close proximity in an office, or to avoid long distance phone charges for teams that are worldwide. It is recommended especially for use in the model where there exists a development box and a live box. The intent is that the development box will host chat as well as development, but the live box will not consume resources intended for web requests on chat. Chat servers use up some network resources and system memory, and should only be used in the scenario where those resources are not an issue: on a development box or a live box with plenty of extra resources.
The XLiRAD AppServer backs up all of its files on a daily basis to a time-stamped subdirectory of the backups directory. The administrator can configure the time for the backup to coincide with a period of low website traffic. The default time is 12:00AM. To change this time, select "Daily Backup" under the "Duplication" menu.
To connect/disconnect the configured database connections, use the "DB Connect" and "DB Disconnect" menu items under the "Execution" menu. To start/stop the XLiRAD port listener, use the "Start Listener" and "Stop Listener" menu items under the "Execution" menu. The prefered order for starting services is to connect to the databases and then start the listener. This is because the second that the port listener is started, active requests requiring database connections will be processed by the server. The prefered order for stopping services is to stop the port listener before disconnecting from the database, for the same reason.
The administrator can lock the XLiRAD server by selecting "Lock Server" under the "Execution" menu. This prevents unathorized users from using any of the menu items of the Server or from shutting the server down. With "Auto Start" in place, the server comes up in a locked state. To unlock the server, the administrator can either try to access any of the menu items and enter the administrative password when prompted or use the "Unlock Server" menu item under the "Execution" menu.
The main display window of the XLiRAD AppServer shows a realtime log of all of the database requests passing through the server, including all of their form data and any errors that occur during processing. The purpose of this window is to be used as a visual debugging tool for the developers as they test their XLiRAD web templates. Often, developers will assume that they have all the necessary form data to satisfy a SQL transaction based upon the flow of their website and not realize that they were missing some. Since the XLiRAD AppServer performs server-side data validation of all SQL requests passing through it, if some data is missing or not of the proper type, the server treats the transaction as an error and returns error data for processing on the template. Developers can use the output window to debug their templates by watching the scrolling log show the SQL statements that were attempted relative to what they thought should have been attempted and find errors in their data handling. All of these executed SQL statements are printed to a date-stamped log file in the logs subdirectory and can be used to rebuild the database if necessary. The server output is a running view into the backup logs. If no visual debugging is necessary, the visual display can be turned off.
Under the "Configuration" menu, there is a checkable menu item, "Display Server Messages." In a checked state, output will be visible in the window; otherwise, the running output is only written to the log files.