28 Repository Access Using Protocols

Enabling the HTTP Listener to Use SSL

A database administrator must carry out the following steps, to configure the HTTP Listener for SSL.

1. Create a wallet for the server and import a certificate – Use Oracle Wallet Manager to do the following:

   1. Create a wallet for the server.

   2. If a valid certificate with distinguished name (DN) of the server is not available, create a certificate request and submit it to a certificate authority. Obtain a valid certificate from the authority.

   3. Import a valid certificate with the distinguished name (DN) of the server into the server.

   4. Save the new wallet in obfuscated form, so that it can be opened without a password.

   See Also:

   Oracle Database Enterprise User Security Administrator's Guide for information about how to create a wallet

2. Specify the wallet location to the server – Use Oracle Net Manager to do this. Ensure that the configuration is saved to disk. This step updates files sqlnet.ora and listener.ora.

3. Disable client authentication at the server, since most Web clients do not have certificates. Use Oracle Net Manager to do this. This step updates file sqlnet.ora.

4. Add an SSL_DH_anon cipher suite to SSL_CIPHER_SUITES – Use any of these:

   • SSL_DH_anon_WITH_3DES_EDE_CBC_SHA

   • SSL_DH_anon_WITH_RC4_128_MD5

   • SSL_DH_anon_WITH_DES_CBC_SHA

   This step updates file sqlnet.ora.

5. Create a listening end point that uses TCP/IP with SSL – Use Oracle Net Manager to do this. This step updates file listener.ora.

Enabling TCPS Dispatcher

A database administrator must edit the database pfile to enable launching of a TCPS dispatcher during database startup. Add the following line to the file, where SID is the SID of the database:

dispatchers=(protocol=tcps)(service=SIDxdb)

The database pfile location depends on your operating system, as follows:

• MS Windows – PARENT/admin/orcl/pfile, where PARENT is the parent folder of folder ORACLE_HOME

• UNIX, Linux – $ORACLE_HOME/admin/$ORACLE_SID/pfile

Nonces for Digest Authentication

A nonce is used with digest authentication. It is a unique string that the server generates each time it issues an HTTP 401 (unauthorized) response. Clients include the nonce in subsequent requests that they issue to the server. The server checks the nonce it receives from the client. If incorrect or if the nonce-timeout period has expired, the server can immediately refuse to authenticate.

(A client can use the same mechanism to authenticate the server: it can generate its own nonce. Both client and server can use this client nonce to help prevent particular plain-text attacks.)

A new nonce is created each time the server sends a digest challenge to a client. A nonce is based on a nonce key. The initial nonce key is generated randomly when you install or upgrade the database.

If you use digest authentication then Oracle also recommends that you create a new nonce key periodically, to ensure the integrity of the key. You use PL/SQL procedure DBMS_XDB_ADMIN.createNonceKey to do this.

FTP Features That Are Not Supported

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 method 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.

Supported FTP Client Methods

For access to the repository, Oracle XML DB supports the following FTP client methods.

• cdup – change working directory to parent directory

• cwd – change working directory

• dele – delete file (not directory)

• list, nlst – list files in working directory

• mkd – create directory

• noop – do nothing (but timeout counter on connection is reset)

• pasv, port – establish a TCP data connection

• pwd – get working directory

• quit – close connection and quit FTP session

• retr – retrieve data using an established connection

• rmd – remove directory

• rnfr, rnto – rename file (two-step process: from file, to file)

• stor – store data using an established connection

• syst – get system version

• type – change data type: ascii or image binary types only

• user, pass – user login

FTP Quote Methods

Oracle Database supports several FTP quote methods, which provide information directly to Oracle XML DB.

• rm_r – Remove file or folder <resource_name>. If a folder, recursively remove all files and folders contained in <resource_name>.

  quote rm_r <resource_name>
  
  

• rm_f – Forcibly remove a resource.

  quote rm_f <resource_name>
  
  

• rm_rf – Combines rm_r and rm_f: Forcibly and recursively removes files and folders.

  quote rm_rf <resource_name>
  
  

• set_nls_locale – Specify the character-set encoding (<charset_name>) to be used for file and directory names in FTP methods (including names in method responses).

  quote set_nls_locale {<charset_name> | NULL} 
  
  

  Only IANA character-set names can be specified for <charset_name>. If nls_locale is set to NULL or is not set, then the database character set is used.

• set_charset – Specify the character set of the data to be sent to the server.

  quote set_charset  {<charset_name> | NULL}
  

  The set_charset method applies to only text files, not binary files, as determined by the file-extension mapping to MIME types that is defined in configuration file xdbconfig.xml.

  If the parameter provided to set_charset is <charset_name> (not NULL), then it specifies the character set of the data.

  If the parameter provided to set_charset is NULL, or if no set_charset command is given, then the MIME type of the data determines the character set for the data.

  • If the MIME type is not text/xml), then the data is not assumed to be XML. The database character set is used.

  • If the MIME type is text/xml, then the data represents an XML document.

    If a byte order mark^Foot 1  (BOM) is present in the XML document, then it determines the character set of the data.

    If there is no BOM, then:

    • If there is an encoding declaration in the XML document, then it determines the character set of the data.

    • If there is no encoding declaration, then the UTF-8 character set is used.

Uploading Content to Oracle XML DB Repository Using FTP

Example 28-2 shows commands issued and output generated when a standard command line FTP tool loads documents into Oracle XML DB Repository:

$ ftp mdrake-sun 2100
Connected to mdrake-sun.
220 mdrake-sun FTP Server (Oracle XML DB/Oracle Database 10g Enterprise Edition
Release 10.1.0.1.0 - Beta) ready.
Name (mdrake-sun:oracle10): QUINE
331 Password required for QUINE
Password: password
230 QUINE logged in
ftp> cd /source/schemas
250 CWD Command successful
ftp> mkdir PurchaseOrders
257 MKD Command successful
ftp> cd PurchaseOrders
250 CWD Command successful
ftp> mkdir 2002
257 MKD Command successful
ftp> cd 2002
250 CWD Command successful
ftp> mkdir "Apr"
257 MKD Command successful
ftp> put "Apr/AMCEWEN-20021009123336171PDT.xml"
"Apr/AMCEWEN-20021009123336171PDT.xml"
200 PORT Command successful
150 ASCII Data Connection
226 ASCII Transfer Complete
local: Apr/AMCEWEN-20021009123336171PDT.xml remote:
Apr/AMCEWEN-20021009123336171PDT.xml
4718 bytes sent in 0.0017 seconds (2683.41 Kbytes/s)
ftp> put "Apr/AMCEWEN-20021009123336271PDT.xml"
"Apr/AMCEWEN-20021009123336271PDT.xml"
200 PORT Command successful
150 ASCII Data Connection
226 ASCII Transfer Complete
local: Apr/AMCEWEN-20021009123336271PDT.xml remote:
Apr/AMCEWEN-20021009123336271PDT.xml
4800 bytes sent in 0.0014 seconds (3357.81 Kbytes/s)
.....
ftp> cd "Apr"
250 CWD Command successful
ftp> ls -l
200 PORT Command successful
150 ASCII Data Connection
-rw-r--r1 QUINE oracle 0 JUN 24 15:41 AMCEWEN-20021009123336171PDT.xml
-rw-r--r1 QUINE oracle 0 JUN 24 15:41 AMCEWEN-20021009123336271PDT.xml
-rw-r--r1 QUINE oracle 0 JUN 24 15:41 EABEL-20021009123336251PDT.xml
-rw-r--r1 QUINE oracle 0 JUN 24 15:41 PTUCKER-20021009123336191PDT.xml
-rw-r--r1 QUINE oracle 0 JUN 24 15:41 PTUCKER-20021009123336291PDT.xml
-rw-r--r1 QUINE oracle 0 JUN 24 15:41 SBELL-20021009123336231PDT.xml
-rw-r--r1 QUINE oracle 0 JUN 24 15:41 SBELL-20021009123336331PDT.xml
-rw-r--r1 QUINE oracle 0 JUN 24 15:41 SKING-20021009123336321PDT.xml
-rw-r--r1 QUINE oracle 0 JUN 24 15:41 SMCCAIN-20021009123336151PDT.xml
-rw-r--r1 QUINE oracle 0 JUN 24 15:41 SMCCAIN-20021009123336341PDT.xml
-rw-r--r1 QUINE oracle 0 JUN 24 15:41 VJONES-20021009123336301PDT.xml
226 ASCII Transfer Complete
remote: -l
959 bytes received in 0.0027 seconds (349.45 Kbytes/s)
ftp> cd ".."
250 CWD Command successful
....
ftp> quit
221 QUIT Goodbye.
$

The key point demonstrated by Figure 28-3 and Example 28-2 is that neither Windows Explorer nor an FTP tool is aware that it is working with Oracle XML DB. Since the tools and Oracle XML DB both support open Internet protocols they work with each other out of the box.

Any tool that understands the WebDAV or FTP protocol can be used to create content managed by Oracle XML DB Repository. No additional software has to installed on the client or the mid-tier.

When the contents of the folders are viewed using a tool such as Windows Explorer or FTP, the length of any schema-based XML documents contained in the folder is shown as zero (0) bytes. This was designed as such for two reasons:

• It is not clear what the size of the document should be. Is it the size of the CLOB instance generated by printing the document, or the number of bytes required to store the objects used to persist the document inside the database?

• Regardless of which definition is chosen, calculating and maintaining this information is costly.

Using FTP with Oracle ASM Files

Oracle Automatic Storage Management (Oracle ASM) organizes database files into disk groups for simplified management and added benefits such as database mirroring and I/O balancing. Database administrators can use protocols and resource APIs to access Oracle ASM files in the Oracle XML DB repository virtual folder /sys/asm. All files in /sys/asm are binary.

Typical uses are listing, copying, moving, creating, and deleting Oracle ASM files and folders. Example 28-3 is an example of navigating the Oracle ASM virtual folder and listing the files in a subfolder.

The structure of the Oracle ASM virtual folder, /sys/asm, is described in Chapter 21, "Accessing Oracle XML DB Repository Data". In Example 28-3, the disk groups are DATA and RECOVERY; the database name is MFG; and the directories created for aliases are dbs and tmp. This example navigates to a subfolder, lists its files, and copies a file to the local file system.

ftp> open myhost 7777
ftp> user system
Password required for SYSTEM
Password: password
ftp> cd /sys/asm
ftp> ls
DATA
RECOVERY
ftp> cd DATA
ftp> ls
dbs
MFG
ftp> cd dbs
ftp> ls
t_dbl.f
t_axl.f
ftp> binary
ftp> get t_dbl.f, t_axl.f
ftp> put my_db2.f

In Example 28-3, after connecting to and logging onto database myhost (first four lines), FTP methods cd and ls are used to navigate and list folders, respectively. When in folder /sys/asm/DATA/dbs, FTP command get is used to copy files t_db1.f and t_ax1.f to the current folder of the local file system. Then, FTP command put is used to copy file my_db2.f from the local file system to folder /sys/asm/DATA/dbs.

Database administrators can copy Oracle Automatic Storage Management (Oracle ASM) files from one database server to another or between the database and a local file system. Example 28-4 shows copying between two databases. For this, the proxy FTP client method can be used, if available. The proxy method provides a direct connection to two different remote FTP servers.

Example 28-4 copies an Oracle ASM file from one database to another. Terms with the suffix 1 correspond to database server1. Terms with the suffix 2 correspond to database server2. Note that, depending on your FTP client, the passwords you type might be echoed on your screen. Take the necessary precautions so that others do not see these passwords.

 1 ftp> open server1 port1
 2 ftp> user username1
 3 Password required for USERNAME1
 4 Password: password-for-username1
 5 ftp> cd /sys/asm/DATAFILE/MFG/DATAFILE
 6 ftp> proxy open server2 port2
 7 ftp> proxy user username2
 8 Password required for USERNAME2
 9 Password: password-for-username2
10 ftp> proxy cd /sys/asm/DATAFILE/MFG/DATAFILE
11 ftp> proxy put dbs2.f tmp1.f
12 ftp> proxy get dbs1.f tmp2.f

In Example 28-4:

• Line 1 opens an FTP control connection to the Oracle XML DB FTP server, server1.

• Lines 2–4 log the database administrator onto server1 as USERNAME1.

• Line 5 navigates to /sys/asm/DATAFILE/MFG/DATAFILE on server1.

• Line 6 opens an FTP control connection to the second database server, server2. At this point, the FTP command proxy ? could be issued to see the available FTP commands on the secondary connection. (This is not shown.)

• Lines 7–9 log the database administrator onto server2 as USERNAME2.

• Line 10 navigates to /sys/asm/DATAFILE/MFG/DATAFILE on server2.

• Line 11 copies Oracle ASM file dbs2.f from server2 to Oracle ASM file tmp1.f on server1.

• Line 12 copies Oracle ASM file dbs1.f from server1 to Oracle ASM file tmp2.f on server2.

Using FTP on the Standard Port Instead of the Oracle XML DB Default Port

You can use the Oracle XML DB configuration file, xdbconfig.xml, to configure FTP to listen on any port. By default, FTP listens on a non-standard, unprotected port. To use FTP on the standard port, 21, your database administrator must do the following:

1. (UNIX only) Use this shell command to ensure that the owner and group of executable file tnslsnr are root:

   % chown root:root $ORACLE_HOME/bin/tnslsnr
   

2. (UNIX only) Add the following entry to the listener file, listener.ora, where hostname is your host name:

   (DESCRIPTION =
     (ADDRESS = (PROTOCOL = TCP) (HOST = hostname) (PORT = 21))
     (PROTOCOL_STACK = (PRESENTATION = FTP) (SESSION = RAW)))
   

3. (UNIX only) Use shell command id to determine the user_id and group_id that were used to install Oracle Database. oracle_installation_user is the name of the user who installed the database.

   % id oracle_installation_user
   uid=user_id(oracle_installation_user) gid=group_id(dba)
   

4. (UNIX only) Stop, then restart the listener, using the following shell commands, where user_id and group_id are the UNIX user and group identifiers obtained in step 3.

   % lsnrctl stop
   % tnslsnr LISTENER -user user_id -group group_id &
   

   Use the ampersand (&), to execute the second command in the background. Do not use lsnrctl start to start the listener.

5. Use PL/SQL procedure DBMS_XDB_CONFIG.setFTPPort with SYS as SYSDBA to set the FTP port number to 21 in the Oracle XML DB configuration file, xdbconfig.xml.

   SQL> exec DBMS_XDB_CONFIG.setFTPPort(21);
   

6. Force the database to reregister with the listener, using this SQL statement:

   SQL> ALTER SYSTEM REGISTER;
   

7. Check that the listener is correctly configured, using this shell command:

   % lsnrctl status
   

Using IPv6 IP Addresses with FTP

Starting with 11g Release 2 (11.2), Oracle Database supports the use of Internet Protocol Version 6, IPv6 (in addition to Internet Protocol Version 4). Example 28-5 shows how to make an FTP connection with the IPv6 address 2001::0db8:ffff:ffff:ffff.

ftp> open 2001::0db8:ffff:ffff:ffff 1521
Connected to 2001::0db8:ffff:ffff:ffff.
220- xmlhost.example.com
Unauthorized use of this FTP server is prohibited and may be subject to civil
and criminal prosecution.
220- xmlhost.example.com FTP server (Oracle XML DB/Oracle Database) ready.
User (2001::0db8:ffff:ffff:ffff:(none)): username
331 pass required for USERNAME
Password: password-for-username
230 USERNAME logged in
ftp>

FTP Server Session Management

Oracle XML DB 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 parameter call-timeout in the Oracle XML DB configuration file. For high traffic sites, 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.

Handling Error 421. Modifying the Default Timeout Value of an FTP Session

If you are frequently disconnected from the server and must reconnect and traverse the entire directory before doing the next operation, you may need to modify the default timeout value for FTP sessions. If the session is idle for more than this period, it gets disconnected. You can increase the timeout value (default = 6000 centiseconds) by modifying the configuration document as follows and then restart the database:

DECLARE
  newconfig XMLType;
BEGIN
SELECT XMLQuery('copy $i := $p1 modify
                   (for $j in $i/xdbconfig/sysconfig/protocolconfig/ftpconfig/session-timeout
                    return replace value of node $j with $p2)
                 return $i'
                PASSING DBMS_XDB_CONFIG.cfg_get() AS "p1", 123456789 AS "p2" RETURNING CONTENT)
  INTO newconfig FROM DUAL;
  DBMS_XDB_CONFIG.cfg_update(newconfig);
END;/
COMMIT;

FTP Client Failure in Passive Mode

Do not use FTP in passive mode to connect remotely to a server that has HOSTNAME configured in listener.ora as localhost or 127.0.0.1. If the HOSTNAME specified in server file listener.ora is localhost or 127.0.0.1, then the server is configured for local use only. If you try to connect remotely to the server using FTP in passive mode, the FTP client fails. This is because the server passes IP address 127.0.0.1 (derived from HOSTNAME) to the client, which makes the client try to connect to itself, not to the server.

Supported HTTP(S) Client Methods

For access to the repository, Oracle XML DB supports the following HTTP(S) client methods.

• OPTIONS – get information about available communication options

• GET – get document/data (including headers)

• HEAD – get headers only, without document body

• PUT – store data in resource

• DELETE – delete resource

The semantics of these HTTP(S) methods is in accordance with WebDAV. Servlets and Web services may support additional HTTP(S) methods, such as POST.

Using HTTP(S) on a Standard Port Instead of an Oracle XML DB Default Port

You can use the Oracle XML DB configuration file, xdbconfig.xml, to configure HTTP(S) to listen on any port. By default, HTTP(S) listens on a non-standard, unprotected port. To use HTTP or HTTPS on a standard port (80 for HTTP, 443 for HTTPS), your database administrator must do the following:

1. (UNIX only) Use this shell command to ensure that the owner and group of executable file tnslsnr are root:

   % chown root:root $ORACLE_HOME/bin/tnslsnr
   

2. (UNIX only) Add the following entry to the listener file, listener.ora, where hostname is your host name, and port_number is 80 for HTTP or 443 for HTTPS:

   (DESCRIPTION =
     (ADDRESS = (PROTOCOL = TCP) (HOST = hostname) (PORT = port_number))
     (PROTOCOL_STACK = (PRESENTATION = HTTP) (SESSION = RAW)))
   

3. (UNIX only) Use shell command id to determine the user_id and group_id that were used to install Oracle Database. oracle_installation_user is the name of the user who installed the database.

   % id oracle_installation_user
   uid=user_id(oracle_installation_user) gid=group_id(dba)
   

4. (UNIX only) Stop, then restart the listener, using the following shell commands, where user_id and group_id are the UNIX user and group identifiers obtained in step 3.

   % lsnrctl stop
   % tnslsnr LISTENER -user user_id -group group_id &
   

   Use the ampersand (&), to execute the second command in the background. Do not use lsnrctl start to start the listener.

5. Use PL/SQL procedure DBMS_XDB_CONFIG.setHTTPPort with SYS as SYSDBA to set the HTTP(S) port number to port_number in the Oracle XML DB configuration file xdbconfig.xml, where port_number is 80 for HTTP or 443 for HTTPS:

   SQL> exec DBMS_XDB_CONFIG.setHTTPPort(port_number);
   

6. Force the database to reregister with the listener, using this SQL statement:

   SQL> ALTER SYSTEM REGISTER;
   

7. Check that the listener is correctly configured:

   % lsnrctl status
   

Using IPv6 IP Addresses with HTTP(S)

Starting with 11g Release 2 (11.2), Oracle Database supports the use of Internet Protocol Version 6, IPv6 (in addition to Internet Protocol Version 4). IPv6 addresses in URLs are enclosed in brackets ([]). Here is an example:

http://[2001::0db8:ffff:ffff:ffff]:8080/

HTTPS: Support for Secure HTTP

If properly configured, you can access Oracle XML DB Repository in a secure fashion, using HTTPS. See "Configuring Secure HTTP (HTTPS)" for configuration information.

Control of URL Expiration Time

Optional configuration parameter expire specifies an HTTP Expires header. This header acts as a directive to the HTTP client, to specify the expiration date and time for a URL.

If cached, the document targeted by a URL can be fetched from the client cache rather than from the server, until this expiration time has passed. After that time, the cache copy is out-of-date and a new copy must be obtained from the source (server).

The Oracle XML DB syntax for the Expires header, which is used in the expire configuration element, is a subset of the so-called alternate syntax defined for the ExpiresDefault directive of the Apache module mod_expires. See http://httpd.apache.org/docs/2.0/mod/mod_expires.html#AltSyn for that syntax.

These are the Oracle XML DB restrictions to the ExpiresDefault syntax:

• You cannot use access as the <base>. Only now and modification are allowed.

• The <type> values must appear in order of decreasing time period. For example, year must appear before, not after, month, since a year is a longer time period than a month.

• You can use at most one occurrence of each of the different <type> values. For example, you cannot have multiple year entries or multiple day entries.

Anonymous Access to Oracle XML DB Repository Using HTTP

Optional configuration parameter allow-repository-anonymous-access controls whether or not anonymous HTTP access to Oracle XML DB Repository data is allowed using an unlocked ANONYMOUS user account. The default value is false, meaning that unauthenticated access to repository data is blocked. To allow anonymous HTTP access to the repository, you must set this parameter to true, and unlock the ANONYMOUS user account.

Parameter allow-repository-anonymous-access does not control anonymous access to the repository using servlets. Each servlet has its own security-role-ref parameter value to control its access.

Use of Java Servlets with HTTP(S)

Oracle XML DB supports Java servlets. To use a Java servlet, it must be registered with a unique name in the Oracle XML DB configuration file, along with parameters to customize its action. 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 application program interface (API) version 2.2.

While processing an HTTP(S) request, the path name for the request is matched with the registered patterns. If there is a match, then 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 invokes a Java method to initialize the servlet, create response, and request objects, pass these on to the servlet, and run it.

Embedded PL/SQL Gateway

You can use the PL/SQL gateway to implement a Web application entirely in PL/SQL. There are two implementations of the PL/SQL gateway:

• mod_plsql – a plug-in of Oracle HTTP Server that lets you invoke PL/SQL stored procedures using HTTP(S). Oracle HTTP Server is a component of both Oracle Fusion Middleware and Oracle Database. Do not confuse Oracle HTTP Server with the HTTP component of the Oracle XML DB protocol server.

• the embedded PL/SQL gateway – a gateway implementation that runs in the Oracle XML DB HTTP listener.

With the PL/SQL gateway (either implementation), a Web browser sends an HTTP(S) request in the form of a URL that identifies a stored procedure and provides it with parameter values. The gateway translates the URL, calls the stored procedure with the parameter values, and returns output (typically HTML) to the Web-browser client.

Using the embedded PL/SQL gateway simplifies installation, configuration, and administration of PL/SQL based Web applications. The embedded gateway uses the Oracle XML DB protocol server, not Oracle HTTP Server. Its configuration is defined by the Oracle XML DB configuration file, xdbconfig.xml. However, the recommended way to configure the embedded gateway is to use the procedures in PL/SQL package DBMS_EPG, not to edit file xdbconfig.xml.

Transmission of Multibyte Data From a Client

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 URL examples that can be sent to Oracle XML DB in an HTTP(S) 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%E3%81%86%E3%83%8F.xml

Oracle 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.

The default-url-charset configuration parameter can be used to accept requests from some clients that use other, nonconforming, forms of URL, with characters that are not ASCII. If a request with such characters fails, try setting this value to the native character set of the client environment. The character set used in such URL fields must be specified with an IANA charset name.

default-url-charset controls the encoding for nonconforming URLs. It is not required to be set unless a nonconforming client that does not send the Content-Type charset is used.

Characters That Are Not ASCII in URLs

Characters that are not ASCII that appear in URLs passed to an HTTP server should be converted to UTF-8 and escaped in the %HH format, where HH is the hexadecimal notation of the byte value. For flexibility, the Oracle XML DB protocol server interprets the incoming URLs by testing whether it is encoded in one of the following character sets in the order presented here:

• UTF-8

• Charset parameter of the Content-Type field of the request, if specified

• Character set, if specified, in the default-url-charset configuration parameter

• Character set of the database

Character Sets for HTTP(S)

The following sections describe how character sets are controlled for data transferred using HTTP(S).

WebDAV Features That Are Not Supported by Oracle XML DB

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

• Lock-NULL resources create zero-length resources in the file system, and cannot be converted to folders.

• Methods COPY, MOVE and DELETE comply with section 2 of the Internet Draft titled 'Binding Extensions to WebDAV'.

• Depth-infinity locks

WebDAV Client Methods Supported by Oracle XML DB

For access to the repository, Oracle XML DB supports the following HTTP(S)/WebDAV client methods.

• PROPFIND (WebDAV-specific) – get properties for a resource

• PROPPATCH (WebDAV-specific) – set or remove resource properties

• LOCK (WebDAV-specific) – lock a resource (create or refresh a lock)

• UNLOCK (WebDAV-specific) – unlock a resource (remove a lock)

• COPY (WebDAV-specific) – copy a resource

• MOVE (WebDAV-specific) – move a resource

• MKCOL (WebDAV-specific) – create a folder resource (collection)

Copying Files into Oracle XML DB Repository Using WebDAV

Figure 28-3 shows Windows Explorer used to insert a folder from the local hard drive into Oracle Database. Windows Explorer includes support for the WebDAV protocol. WebDAV extends the HTTP standard, adding additional verbs that allow an HTTP server to act as a file server.

When a Windows Explorer copy operation or FTP input command is used to transfer a number of documents into Oracle XML DB Repository, each put or post command is treated as a separate atomic operation. This ensures that the client does not get confused if one of the file transfers fails. It also means that changes made to a document through a protocol are visible to other users as soon as the request has been processed.

Figure 28-3 Copying Files into Oracle XML DB Repository

Description of "Figure 28-3 Copying Files into Oracle XML DB Repository"