|Texxmlserver and PHP Objects|
Texxmlserver was designed to provide a standards-compliant database interface to Texpress for the development of web applications and services. Texxmlserver provides XML over HTTP access to Texpress Databases.
Texxmlserver conforms to the following standards:
The majority of web development is undertaken using scripting language such as PHP, JSP, ASP, or Perl. Interfacing a database with a script language usually involves language and database specific drivers. Texxmlserver improves on traditional database interfacing by using the web's own connection protocol; HTTP. This has the following advantages:
How it works
Texxmlserver is a resident server daemon like Apache or Sendmail. It listens on a TCP port for incoming HTTP connections. When a HTTP request is received, Texxmlserver will look for a TEXQL (KE Texpress' enhanced SQL) query request in the prescribed format. The server executes the query or statement and return the results formatted as an XML document.
A scripting language would perform the following functions to interface with the Texxmlserver:
The XML returned from Texxmlserver is designed to be light-weight, fast and easily parsed. KE Texpress is an object oriented database. XML is an ideal format for representing Texpress's hierarchical data. Users can continue to take advantage of Texpress's nested table/column support.
Planning Your Installation
Texxmlserver is a resident daemon process. It should be installed under the express account on the same server that hosts the KE Texpress databases. Texxmlserver should be started at system boot.
Texxmlserver is usually accessed via a scripting language run on a Web Server. The Web Server and the Database Server running Texxmlserver may be located on the same machine. Alternatively the Database Server may be installed on a separate system (possibly behind a firewall). The Database Server and the Web Server should be connected via TCP/IP.
Texxmlserver is a component of the Texpress API. The TexAPI is a separate component of Texpress. Please see the KE Software website for details. Texxmlserver is available in TexAPI version 3.1.002 or higher.
Step 1. Install TexAPI
Install TexAPI as per the TexAPI install notes. Ensure that the texapi/bin directory is on the PATH.
Step 2. Create a working directory
Texxmlserver needs a working directory [base directory]. It expects to find the texxmlserver.conf file in this directory and will also store its access logs here. The texxmlserver.conf file is stored in texapi/etc. You may opt to use this as your base directory. If you set-up an alternate location, copy texapi/etc/texxmlserver.conf into this location.
Step 3. Preparing your databases
KE Texpress databases should be in an accessible state before starting Texxmlserver.
Step 4. Edit the configuration file
The Texxmlserver configuration file should be edited as appropriate. The key setting to modify is the "AllowedHosts". Your Web Server's address/name should be added to the list. If the Web Server is running on the same physical system as Texxmlserver, then the default setting of "localhost" will be satisfactory.
Configuration is also possible with command-line options on texxmlctl. Run
texxmlctl start --help
for details. Any command-line options override the configuration file.
Step 5. Starting Texxmlserver
Texxmlserver is controlled by texxmlctl. This command accepts "start", "stop" and "restart" options. Start Texxmlserver manually with the command:
texxmlctl -b ~/texapi/etc start
Step 6. Testing
The simplest method of testing Texxmlserver is with a Web Browser such as MS Internet Explorer. Open the browser and enter a URL such as:
[ replace myserver.address with the address of the server running Texxmlserver - "database" should be replaced with a name of a valid Texpress database. ]
The contents of the database should display in XML.
Note: The system you are attempting to connect from should be an "AllowedHost" set in texxmlserver.conf.
Starting Texxmlserver on Boot
The following command can be placed in your system's local boot file to start texxmlserver automatically after boot:
su texpress -c "(. /home/texpress/.profile;
The "AllowedHosts" directive in the texxmlserver.conf file offers strong access control. Only these trusted hosts (i.e. the web server) will be granted access to Texpress databases via Texxmlserver.
Texxmlserver can also control access via an "Authentication Token". The authentication token is a "secret" word or phrase that's defined in the texxmlserver.conf file. Access is only granted to connections that have the secret word in a URI field called "auth". An example is:
The texxmlserver.conf file contains:
A valid request:
Additional security on the operating system level should be considered. Methods include:
Interfacing with Texxmlserver
Any scripting language with an HTTP request library and XML Parser will be able to retrieve and use data via Texxmlserver. All major web scripting languages provide the required libraries. Texxmlserver currently provides a high level interface API for accessing Texxmlserver via the PHP. The PHP library interface is located in examples/texxmlserver/php/texquery.php . This file can be "included" or "required" in PHP pages. PHP example code and notes are provided.
Other web script languages may interface with Texxmlserver using their HTTP/XML Libraries. All Query/TEXQL requests must conform to the following format:
1. TCP Protocol
2. Valid HTTP "GET" or "POST" request as defined in the HTTP/1.0 standard.
3. The URL request should contain a command in the form texql=[url encoded TEXQL statement]
An example of a full request is:
GET /?texlq=Select+Title%2C+Year+from+Movies+Where+Year+%3D+2001 HTTP/1.0
TEXQL Update, Insert and Delete operations are permitted. Developers should check the success of the TEXQL command by inspecting the "status" attribute in the top level <results> tag. (see XML Format Overview).
XML Format Overview
The XML produced by Texxmlserver is designed to be as light-weight as possible for fast transfer and parsing. This is an important aspect for dynamic web development. No Field/Column type information is transmitted (date, float, text, etc.). The developer is expected to know the structure of the database and know how to handle the field content data. If you require an XML data file with type information, please have a look at the command-line utility texxmlexport. Future versions of XML server may provide more verbose XML mark-up schemas.
The following format rules are applied to a query results set.
Level 1. The top-level (or Root) tag is <results>
Level 2. Denotes the start and end of a database record
Level 3. Top level KE Texpress Column (Atom, Tuple or Nested Table)
name: [KE Texpress column ID]
Level 4. Item in a Nested Table.
name: [KE Texpress column ID]
Example XML Output
TEXQL Query: SELECT MovieTitle, Year FROM Movies
URL Request: http://server.address/?texql=Select+MovieTitle%2C+Year+From+Movies
<?xml version="1.0" ?>
TEXQL Query: SELECT MovieTitle, Actors_tab FROM Movies
URL Request: http://server.address/?texql=Select+MovieTitle%2C+Actors_tab+From+Movies
<?xml version="1.0" ?>