Skip Headers

Oracle9i XML Database Developer's Guide - Oracle XML DB
Release 2 (9.2)

Part Number A96620-02
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Feedback

Go to previous page Go to next page
View PDF

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.

See Also:

"Accessing Oracle XML DB Resources Using Internet Protocols"

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.

See Also:

Chapter 20, "Writing Oracle XML DB Applications in Java"

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.

See Also:

Appendix A, "Installing and Configuring Oracle XML DB".

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

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:

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.

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:

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:

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.

See Also:

Chapter 20, "Writing Oracle XML DB Applications in Java"

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:

  1. Attempts to decode the multibyte data in UTF-8. If this is not valid.
  2. Uses the Content-Type charset header value. If the data is not encoded in that encoding then.
  3. If the default-url-charset configuration value is specified, It attempts to decode the value using that character set.
  4. 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:

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:

Oracle XML DB's Non-Supported WebDAV Features

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

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

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

  1. From your desktop, select My Network Places.
  2. Double click "Add Network Place".
  3. Type the location of the folder, for example:
    http://[Oracle server name]:<HTTP port number>
    
    

    See Figure 19-2.

  4. Click Next.
  5. Enter any name to identify this WebFolder
  6. 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