This introduction summarizes the methods available for programming against the X-Machine using HTTP requests.
The information in this introduction is organized under the following headings:
Tamino's X-Machine can store and retrieve XML documents as well as non-XML documents. In X-Machine terms, XML documents are well-formed XML documents.
X-Machine provides two methods of accessing documents:
Using plain URL addressing: Individual documents can be addressed using a URL in an HTTP GET, PUT, DELETE or HEAD request. The URL reflects a certain directory path structure that addresses the document uniquely. If you want to access a non-XML document in Tamino, you must use this method. With plain URL addressing, X-Machine behaves like an HTTP server, meaning that the response is returned only via HTTP mechanisms and HTTP-related return codes. If a document is requested using the GET method, it is returned in the HTTP response body.
This access method is described in the section Requests using Plain URL Addressing.
Using X-Machine commands: This access method allows special commands to be sent to the X-Machine either in URLs that are sent using the HTTP GET method or as HTML form data that is sent using the HTTP POST method.
If the GET method is used, the commands are provided in the URL as
keyword/value pairs in the search part of the URL (as defined in
section 3.3, HTTP of the IETF document
RFC1738,
http://www.ietf.org/rfc/rfc1738.txt).
The URL path is separated from the commands by a question mark
("?"). If there are two or more commands in a single
URL, they are separated by an ampersand character
("&").
This access method is described in the section Requests using X-Machine Commands.
X-Machine commands support all of the X-Machine functionality provided by plain URL addressing and support a wide range of additional operations. The X-Machine responds to each request with an appropriate X-Machine response document inside the HTTP response body rather than returning a plain HTTP response. If, for example, an application requests a set of documents to be returned from the X-Machine, the returned documents are enclosed by default in the HTTP response body inside an XML wrapper. This wrapper consists of elements and attributes defined in the Tamino namespace http://namespaces.softwareag.com/tamino/response2 using the prefix "ino", such as Tamino return codes and cursor information. The wrapper can be suppressed; see the section Suppressing the Tamino Response Wrapper for further information.
When storing and retrieving documents, the following rules apply:
The X-Machine converts XML documents to Unicode before storing them in Tamino.
By default, the X-Machine converts non-XML text documents to Unicode
before storing them in Tamino. However, there is an option to suppress this
conversion, i.e. to store and retrieve the documents unconverted. This option
is activated by specifying the element tsd:noConversion
as a child of the element tsd:nonXML in
the schema for the non-XML doctype. See the
description of the element
tsd:nonXML in the Schema Reference Guide
for more information.
When tsd:noConversion
is specified, documents are processed as follows:
When a document is stored the character encoding which was given in
the HTTP request in the Content-Type field is stored.
Indexing can be performed on a non-XML document only if the character coding is given in the HTTP header.
When a document is retrieved, the data is returned without any
conversion being performed. This applies even if the
Accept-Charset HTTP header field is set. If a character encoding
was specified in the HTTP header when the data was stored, this character
encoding is returned in the header of the HTTP response.
Binary documents are stored and retrieved unchanged byte for byte in Tamino.
See the section Media Type Requirements for a description of how Tamino distinguishes between XML and non-XML documents.
Security for Tamino databases can be implemented using Tamino's built-in security mechanism that is based on entries in a special collection called ino:security. This is described in detail in the Security section of the documentation for Tamino Manager.
In addition, some limited security mechanisms are offered by the web server if a web server is used as the interface to Tamino. By configuring the web server, protection is possible at the database level. This controls access to databases, using the same mechanism as for ordinary directory structures under the control of the web server.
Note however that security mechanisms based on the web server are limited in use. It is for example not possible to set security at the collection level because XQuery can be used to access data across collection boundaries.
If a request is made to store an XML or non-XML document, but the request contains no collection name, the document will be stored in the collection ino:etc. In such cases, XML documents and non-XML documents consisting of text are stored with text retrieval indexing applied to the whole document, and non-XML documents (regardless of whether they consist of text or not) are stored in the special doctype ino:nonXML within ino:etc.
The collection ino:etc is always present in every defined database.
