Getting a document by its name

How to: retrieve a document when you know its name; save a document's content as a file encoded in Unicode UTF-16LE; retrieve a document's properties.

The program must be connected to a docbase, and it must have an IxiaDocBaseServices object for that docbase:

IxiaDocBaseServices docbase =    ...

The simplest way to retrieve a document is to know its name. A document name is similar to a file name in Windows or Linux. (If you don't already know the document name, then you must search for the document.)

Usually, you want to retrieve a list of documents; accordingly, you must prepare an array of document names even if you only want to retrieve one document.

Often, you want to save the contents of a document as a file. We will show you how to save it in the Unicode UTF-16LE character encoding, that is, in the 16-bit, little-endian Unicode standard. This encoding is used by recent versions of Microsoft Windows when saving in Unicode.

To retrieve a document by name, and then to save it as a file:

Get the DocumentServices object for the document base that contains the document or documents to be retrieved.
```
// Get DocumentServices for <docbase>
IxiaDocumentServices ds = docbase.DocumentServices();
```
Prepare an array with one element: a string containing the name of the document to retrieve.
```
String [] documents = new String[1];
documents[0] = documentName;
```
To retrieve more than one document: create an array of the appropriate size, then set each element to the name of a document.
Get the document from the docbase.
```
IxiaDocumentServices.Result [] result =
    ds.GetDocuments(documents,
        Constants.TEXTML_DOCUMENT_CONTENT |
        Constants.TEXTML_DOCUMENT_PROPERTIES,
        Constants.TEXTML_DOCUMENT);
```
Let's look at the second argument; we are OR-ing two flags:
- Constants.TEXTML_DOCUMENT_CONTENTTextmlConstants.TEXTML_DOCUMENT_CONTENT: Retrieve the contents of the document.
- : Retrieve the properties of the document, i.e., the document's MIME type, date created, date modified, size, and so forth.
Accordingly, the second argument means "Retrieve the document's contents and properties."

The third argument, Constants.TEXTML_DOCUMENT, means "Retrieve user document(s)." Note that TEXTML Server stores two kinds of documents:
- User documents are documents stored by users of the application that you are developing.
- System documents are DTDs, index definition files, format files, and so forth.
The call returns a Result object. A Result object is an array of the same size as the array of file names to retrieve. Each element has two fields:
- A document object (class IxiaDocument).
- An error object (class TextmlserverError)
Before we process the document, we must make sure that there was no error returned for that document.
For each document to be retrieved, check whether any error was returned:
```
if (result[0].error != null)
{
    System.err.println
      ("The following error occurred while getting " +  documentName);
    System.err.println(result[0].error.getMessage());
    return;
}
```
If you have more than one document to retrieve, you must index through the result array: for each element in the array, if no error object has been returned, then process the returned document (by, e.g., saving it to disk).
Save the returned document's content (normally text coded in XML) to a disk file:
```
// Save the document's content to the <path> specified.
// WriteFile() is defined in sample program GetDocument.cs.
// It writes a string to a path\filename.
WriteFile(path + File.separator + documentName,
          result[0].document.GetContent());

System.out.println(documentName + " successfully saved.") ;
```
Usually, the contents of a TEXTML SDK object is text coded in XML; if so, the MIME type will normally be "text/xml". TEXTML Server can also store binary files with MIME types such as "image/jpeg", "audio/mpeg3", and "application/zip".

MIME type is an example of a document property. These properties include the size of the document's contents in bytes, the date and time that the document was created, and the date and time that the document was last modified. TEXTML Server stores and manages the properties for each document in a docbase.

Save the returned document's properties to a separate disk file:

// WriteFile() writes a string to a disk file
WriteFile
    (path + File.separator + "P_" + result[0].document.GetName() + ".xml",
     result[0].document.GetProperties());

System.out.println(documentName + "'s properties successfully saved.");

The document properties are always returned as an XML string. Here are the properties of a typical document:

<?xml version='1.0' encoding='UTF-16' ?>
<documentproperties>
    <systemproperties>
        <collection>/</collection>
        <name>20000701TS0000000750.XML</name>
        <version>1</version>
        <size>10776</size>
        <indexable>true</indexable>
        <textmldoctype>TEXTML_DOCUMENT</textmldoctype>
        <storagetype>TEXT_BE</storagetype>
        <mimetype>text/xml</mimetype>
        <creatorinfo>
            <user>devel@ixiasoft</user>
            <time>16:05:28</time>
            <date>2010-05-20</date>
        </creatorinfo>
        <modifierinfo>
            <user>devel@ixiasoft</user>
            <time>16:05:28</time>
            <date>2010-05-20</date>
        </modifierinfo>
    </systemproperties>
    <otherproperties>
        <versionsinfo>
            <currentdocumentversion>1</currentdocumentversion>
            <previousversionscount>0</previousversionscount>
            <previousversionstotalsize>0</previousversionstotalsize>
        </versionsinfo>
    </otherproperties>
</documentproperties>

Note: You can define custom properties for your documents: TEXTML Server will store, manage, and retrieve them along with the standard properties.

You can build and run this sample program:

[...]\IxiaSoft\TextmlServer45\...\GetDocuments.Java