19
Using FTP, HTTP, and WebDAV Protocols

This chapter describes how to access Oracle XML DB Repository using FTP, HTTP/WebDAV protocols. It contains the following sections:

Introducing Oracle XML DB Protocol Server

As described in Chapter 2, "Getting Started with Oracle XML DB" and Chapter 13, "Oracle XML DB Foldering", Oracle XML DB Repository provides a hierarchical data repository in the database modeled on XML. Oracle XML DB Repository maps path names (or URLs) onto database objects of XMLType and provides management facilities for these objects.

Oracle XML DB also provides the Oracle XML DB Protocol Server. This supports standard Internet protocols, FTP, WebDAV, and HTTP, for accessing its hierarchical repository/ file system. Since XML documents reference each other using URLs, typically HTTP URLs, Oracle XML DB Repository and its protocol support are important Oracle XML DB components. These protocols can provide direct access to Oracle XML DB to many users without having to install additional software.

Session Pooling

Oracle XML DB Protocol Server maintains a shared pool of sessions. Each protocol connection is associated with one session from this pool. After a connection is closed the session is put back into the shared pool and can be used to serve later connections.

HTTP Performance is Improved

Session Pooling improves performance of HTTP by avoiding the cost of re-creating session states, especially when using HTTP 1.0, which creates new connections for each request. For example, a couple of small files can be retrieved by an existing HTTP/1.1 connection in the time necessary to create a database session. You can tune the number of sessions in the pool by setting session-pool-size in Oracle XML DB's xdbconfig.xml file, or disable it by setting pool size to zero.

Java Servlets

Session pooling can affect users writing Java servlets, since other users can come along and see session state initialized by another request for a different user. Hence, servlet writers should only use session memory, such as, Java static variables, to hold data for the entire application rather than for a particular user. Per user state must be stored in the database or in a look-up table rather than assuming a session will only exist for a single user.

Figure 19-1 illustrates the Oracle XML DB Protocol Server components and how they are used to access files in Oracle XML DB XML Repository and other data. Only the relevant components of the Repository are shown

Figure 19-1 Oracle XML DB Architecture: Protocol Server

Text description of adxdb019.gif follows

Text description of the illustration adxdb019.gif

Oracle XML DB Protocol Server Configuration Management

Oracle XML DB Protocol Server uses configuration parameters stored in /xdbconfig.xml to initialize its startup state and manage session level configuration.The following section describes the protocol-specific configuration parameters that you can configure in the Oracle XML DB configuration file.

Configuring Protocol Server Parameters

Table 19-1 shows the parameters common to all protocols. All parameter names in this table, except those starting with /xdbconfig, are relative to the following XPath in the Oracle XML DB configuration schema:

/xdbconfig/sysconfig/protocolconfig/common

FTP-specific parameters. Table 19-2 shows the FTP-specific parameters. These are relative to the following XPath in the Oracle XML DB configuration schema:
```
/xdbconfig/sysconfig/protocolconfig/ftpconfig
```
HTTP/WebDAV specific parameters except servlet-related parameters. Table 19-3 shows the HTTP/WebDAV-specific parameters. These parameters are relative to the following XPath in the Oracle XML DB configuration schema:
```
/xdbconfig/sysconfig/protocolconfig/httpconfig
```

For examples of the usage of these parameters, see the configuration file /xdbconfig.xml, listed in Appendix A, "Installing and Configuring Oracle XML DB" and Appendix G, "Example Setup scripts. Oracle XML DB - Supplied XML Schemas", the section, "xdbconfig.xsd: XML Schema for Configuring Oracle XML DB".

Table 19-1 Common Protocol Configuration Parameters

Parameter	Description
extension-mappings/mime-mappings	Specifies the mapping of file extensions to mime types. When a resource is stored in the Oracle XML DB Repository, and its mime type is not specified, this list of mappings is used to set its mime type.
extension-mappings/lang-mappings	Specifies the mapping of file extensions to languages. When a resource is stored in the Oracle XML DB Repository, and its language is not specified, this list of mappings is used to set its language.
extension-mappings/encoding-mappings	Specifies the mapping of file extensions to encodings. When a resource is stored in the Oracle XML DB Repository, and its encoding is not specified, this list of mappings is used to set its encoding.
extension-mappings/charset-mappings	Specifies the mapping of file extensions to character sets. When a resource is stored in the Oracle XML DB Repository, and its character set is not specified, this list of mappings is used to set its character set.
session-pool-size	Maximum number of sessions that are kept in the protocol server's session pool
/xdbconfig/sysconfig/call-timeout	If a connection is idle for this time (in hundredths of a second), the shared server serving the connection is freed up to serve other connections.
session-timeout	Time (in hundredths of a second) after which a session (and consequently the corresponding connection) will be terminated by the protocol server if the connection has been idle for that time. This parameter is used only if the specific protocol's session timeout is not present in the configuration
/xdbconfig/sysconfig/default-lock-timeout	Time after which a WebDAV lock on a resource becomes invalid. This could be overridden by a Timeout specified by the client that locks the resource.

Table 19-2 Configuration Parameters Specific to FTP

Parameter	Description
ftp-port	Port on which FTP server listens. By default this is 2100
ftp-protocol	Protocol over which the FTP server runs. By default this is tcp
session-timeout	Time (in hundredths of a second) after which an FTP session (and consequently the corresponding connection) will be terminated by the protocol server if the connection has been idle for that time.

Table 19-3 Configuration Parameters Specific to HTTP/WebDAV (Except Servlet Parameters)

Parameter	Description
http-port	Port on which HTTP/WebDAV server listens
http-protocol	Protocol over which the HTTP/WebDAV server runs. By default this is tcp
session-timeout	Time (in hundredths of a second) after which an HTTP session (and consequently the corresponding connection) will be terminated by the protocol server if the connection has been idle for that time.
server-name	The value of the Server header in an HTTP response
max-header-size	Maximum size (in bytes) of an HTTP header
max-request-body	Maximum size (in bytes) of an HTTP request body
webappconfig/welcome-file-list	List of filenames that are considered "welcome files". When an HTTP GET request for a container is received, the server first checks if there's a resource in the container with any of these names. If so, the contents of that file are sent, instead of a list of resources in the container.
default-url-charset	The character set in which an HTTP Protocol Server assumes incoming URL is encoded when it is not encoded in UTF-8 or the request's Content-Type field Charset parameter.

Interaction with Oracle XML DB Filesystem Resources

The protocol specifications, RFC 959 (FTP), RFC 2616 (HTTP), and RFC 2518 (WebDAV) implicitly assume an abstract, hierarchical file system on the server side. This is mapped to the Oracle XML DB hierarchical Repository. Oracle XML DB Repository provides features such as:

Name resolution
ACL-based security
The ability to store and retrieve any content. Oracle XML DB Repository can store both binary data input through FTP and XML schema-based documents.
See Also:

http://rfc.sunsite.dk/rfc/rfc959.html

http://256.com/gray/docs/rfc2616/

http://www.faqs.org/rfcs/rfc2518.html

Protocol Server Handles XML Schema-Based or Non-Schema-Based XML Documents

Oracle XML DB Protocol Server enhances the protocols by always checking if XML documents being inserted are based on XML schemas registered in the Repository.

If the incoming XML document specifies an XML schema, the Oracle XML DB storage to use is decided by that XML schema. This functionality comes in handy when you need to store XML documents object-relationally in the database, using simple protocols like FTP or WebDAV instead of having to write SQL statements.
If the incoming XML document is not XML schema-based, it is stored as a binary document.

Event-Based Logging

In certain cases, it may be useful to log the requests received and responses sent by a protocol server. This can be achieved by setting event number 31098 to level 2. To set this event, add the following line to init.ora and restart the database:

event="31098 trace name context forever, level 2"

Using FTP and Oracle XML DB Protocol Server

The following sections describe FTP features supported by Oracle XML DB.

Oracle XML DB Protocol Server: FTP Features

File Transfer Protocol (FTP) is one of the oldest and most popular protocols on the net. FTP is specified in RFC959 and provides access to heterogeneous file systems in a uniform manner. FTP works by providing well defined commands for communication between the client and the server. The transfer of commands and the return status happens on a single connection. However, a new connection is opened between the client and the server for data transfer. In HTTP, the transfer of commands and data happens on a single connection.

FTP is implemented by both dedicated clients at the operating system level, file system explorer clients, and browsers. FTP is typically session-oriented, in that a user session is created through an explicit logon, a number of files / directories are downloaded and browsed, and then the connection is closed.

See Also:

RFC 959: FTP Protocol Specification

Non-Supported FTP Features

Oracle XML DB implements FTP, as defined by RFC 959, with the exception of the following optional features:

Record-oriented files, for example, only the FILE structure of the STRU command is supported. This is the most widely used structure for transfer of files. It is also the default specified by the specification. Structure mount is not supported.
Append.
Allocate. This pre-allocates space before file transfer.
Account. This uses the insecure Telnet protocol.
Abort.

Using FTP on Standard or Non-Standard Ports

It can be configured through the Oracle XML DB configuration file /xdbconfig.xml, to listen on an arbitrary port. FTP ships listening on a non-standard, non-protected port. To use FTP on the standard port (21), your DBA has to chown the TNS listener to setuid ROOT rather than setuid ORACLE.

FTP Server Session Management

Protocol Server also provides session management for this protocol. After a short wait for a new command, FTP returns to the protocol layer and the shared server is freed up to serve other connections. The duration of this short wait is configurable by changing the call-timeOut parameter in the Oracle XML DB configuration file. For high traffic sites, the call-timeout should be shorter so that more connections can be served. When new data arrives on the connection, the FTP Server is re-invoked with fresh data. So, the long running nature of FTP does not affect the number of connections which can be made to the Protocol Server.

Using HTTP and Oracle XML DB Protocol Server

Oracle XML DB implements HyperText Transfer Protocol (HTTP), HTTP 1.1 as defined in RFC2616 specification. In this release, Oracle XML DB Protocol Server also supports the HTTP protocol extension, RFC 2109 "HTTP State Management", that is "cookies".

Oracle XML DB Protocol Server: HTTP Features

The Oracle XML DB HTTP component in the Oracle XML DB Protocol Server implements the RFC2616 specification with the exception of the following optional features:

gzip and compress transfer enco1dings
byte-range headers
The TRACE method (used for proxy error debugging)
Cache-Control directives (requires you to specify expiration dates for content, and are not generally used)
TE, Trailer, Vary & Warning headers
Weak entity tags
Web common log format
Multi-homed Web server

See Also:
RFC 2616: HTTP 1.1 Protocol Specification

Non-Supported HTTP Features

Oracle XML DB does not implement the new Set-Cookie2 header specified in RFC 2965, as most of the Internet community is not yet using it. Digest Authentication (RFC 2617) is not supported. In this release, Oracle XML DB supports Basic Authentication, where a client sends the user name and password in clear text in the "Authorization" header.

Using HTTP on Standard or Non-Standard Ports

HTTP ships listening on a non-standard, non-protected port (8080). To use HTTP on the standard port (80), your DBA must chown the TNS listener to setuid ROOT rather than setuid ORACLE, and configure the port number in the Oracle XML DB configuration file /xdbconfig.xml.

HTTP Server and Java Servlets

Oracle XML DB supports Java servlets. To use a servlet, it must be registered with a unique name in the Oracle XML DB configuration file, along with parameters to customize its behavior. It should be compiled, and loaded into the database. Finally, the servlet name must be associated with a pattern, which can be an extension such as "*.jsp" or a path name such as "/a/b/c" or "/sys/*", as described in Java servlet API version 2.2.

While processing an HTTP request, the path name for the request is matched with the registered patterns. If there is a match, the Protocol Server invokes the corresponding servlet with the appropriate initialization parameters. For Java servlets, the existing Java Virtual Machine (JVM) infrastructure is used. This starts the JVM if need be, which in turn runs a Java method to initialize the servlet, create response, and request objects, pass these on to the servlet, and run it.

Non-ASCII Characters in URLs

When a client sends multibyte data in a URL, RFC 2718 specifies that the client should send the URL using the %HH format where HH is the hexadecimal notation of the byte value in UTF-8 encoding. The following are some URL examples that can be sent to XML DB in either an HTTP or WebDAV context:

http://urltest/xyz%E3%81%82%E3%82%A2 
http://%E3%81%82%E3%82%A2 
http://%E3%81%82%E3%82%A2/abc%81%86%E3%83%8F.xml

XML DB processes the requested URL, any URLs within an IF header, any URLs within the DESTINATION header, and any URLs in the REFERRED header that contains multibyte data.

Some clients may either not encode the hexadecimal value in UTF-8, or completely disregard the %HH notation and send straight multibyte data. XML DB handles these non-conforming clients by following a specific algorithm. The URL is processed as follows:

Attempts to decode the multibyte data in UTF-8. If this is not valid.
Uses the Content-Type charset header value. If the data is not encoded in that encoding then.
If the default-url-charset configuration value is specified, It attempts to decode the value using that character set.
Finally, it assumes it is in the database character set.

Here are some examples of non-conforming URLs:

http://urltest/ã?,ã??ã??ã?^ 
http://urltest/xyz%<shift-jis HH encoding>%<shift-jis HH encoding>

The default-url-charset must be an IANA name.

Using WebDAV and Oracle XML DB

Web Distributed Authoring and Versioning (WebDAV) is a standard protocol used to provide users with a file system interface to Oracle XML Repository over the Internet. The most popular way of accessing a WebDAV server folder is through "WebFolders" on Microsoft Windows 2000 or Microsoft NT.

WebDAV is an extension to HTTP 1.1 protocol. It allows clients to perform remote web content authoring through a coherent set of methods, headers, request body formats and response body formats. WebDAV provides operations to store and retrieve resources, create and list contents of resource collections, lock resources for concurrent access in a coordinated manner, and to set and retrieve resource properties.

Oracle XML DB WebDav Features

Oracle XML DB supports the following WebDAV features:

Foldering, specified by RFC2518
Access Control

WebDAV is a set of extensions to the HTTP protocol that allow you to edit or manage your files on remote Web servers. WebDav can also be used, for example, to:

Share documents over the Internet
Edit content over the Internet

See Also:
RFC 2518: WebDAV Protocol Specification

Oracle XML DB's Non-Supported WebDAV Features

Oracle XML DB supports the contents of RFC2518, with the following exceptions:

Lock-NULL resources create actual zero-length resources in the file system, and cannot be converted to folders.
Implementing the WebDAV ACL protocol and binding protocol
Depth-infinity locks
Only Basic Authentication is supported

Using Oracle XML DB and WebDAV: Creating a WebFolder in Windows 2000

To create a WebFolder in Windows 2000, follow these steps:

From your desktop, select My Network Places.
Double click "Add Network Place".
Type the location of the folder, for example:
```
http://[Oracle server name]:<HTTP port number>
```
See Figure 19-2.
Click Next.
Enter any name to identify this WebFolder
Click Finish.

You can now access Oracle XML DB Repository just like you access any Windows folder.

Figure 19-2 Creating a WebFolder in Windows 2000

Text description of webfolder.jpg follows.

Text description of the illustration webfolder.jpg

19 Using FTP, HTTP, and WebDAV Protocols