5 Uploading and Downloading Using Web Services

Content Services allows you to post and retrieve documents between a client and a Web Services instance using the DAV (Distributed Authoring and Versioning) protocol.

For this example, you will need the following managers:

• File Manager - For creating a file on the Web Services instance when uploading, and resolving folder names

• Session Manager - for maintaining the Manager sessions

You will also need to use the HTTPConnection class to connect to the DAV server when uploading and downloading. This class is included as part of the iAS HTTPClient library.

Uploading

The first step in uploading a document to the server is to create a new DocumentDefinition Item on the server. To do this, use the FileManager.createDocumentDefinition() method, which creates a DOCUMENT_DEFINITION Item on the server. This Item acts as a placeholder for a Document prior to uploading its contents. Pass an AttributeRequest to the FileManager method call to retrieve the fully resolved URL (Attributes.URL) of this Document. This URL is later used to upload the content.

/**
 * Creates a new Document with the specified content.
 */
public static Item uploadDocument(String folderPath, String docName,
    byte[] content) throws FdkException, IOException, ModuleException
{
    // get the Manager instance we need
    FileManager fm = WsConnection.getFileManager();
 
    // create an AttributeRequest[] for the URL attribute
    AttributeRequest[] urlAR = WsUtility
        .newAttributeRequestArray(Attributes.URL);
 
    // create a DOCUMENT_DEFINITION Item
    //     -> a temporary, persistent document definition into which content
    //        can be uploaded using HTTP
    //     -> notice that we request the URL attribute for the Item that is
    //        returned; we will use the URL to upload contents to the docDef
    Item docDef = fm.createDocumentDefinition(
        WsUtility.newNamedValueArray(new Object[][] { 
        { Attributes.NAME, docName } }), urlAR);

Now that the placeholder document exists, open an HTTP connection to it using the URL returned by the AttributeRequest, and transfer the data using the HTTPConnection.put() method.

For convenience, this section uses the ClientUtils class, which is a set of data type operators and utility methods for Web Services clients. To extract the URL attribute, a Map is created from the requested attribute set using the ClientUtils.namedValuesToMap method, and the URL retrieved using the Map.get method. This technique offers the advantage of being able to retrieve the attributes by name, instead of having to iterate over the array.

This example also uses a helper method called createHttpConnection(), which is explained at the end of this section.

// get the URL attribute from the docDef Item
    NamedValue[] attrs = docDef.getRequestedAttributes();
    Map attrMap = ClientUtils.namedValuesToMap(attrs);
    String docUrl = (String) attrMap.get(Attributes.URL);
    URL url = new URL(docUrl);
 
    // upload content into docDef using HTTP
    HTTPConnection httpCon = createHttpConnection(url);
    HTTPResponse rsp = httpCon.Put(url.getFile(), content);
 
    // check the response
    if (rsp.getStatusCode() >= 300)
    {
        System.err.println("Error: " + rsp.getReasonLine());
    }

Once the content is uploaded, create the final document using the FileManager by passing in the destination folder and the document definition. The USE_SAVED_DEFINITION option instructs the FileManager to use the newly created document definition (docDef) as the basis for this new document.

// create the Document using the docDef
    Item folder = fm.resolvePath(folderPath, null);
    Item newDoc = fm.createDocument(
    WsUtility.newNamedValueArray(new Object[][] {
        { Options.DESTFOLDER, new Long(folder.getId()) },
        { Options.USE_SAVED_DEFINITION, new Long(docDef.getId()) } }), null,
            urlAR);
 
    return newDoc;
}

Now, the helper method:

/**
 * Creates an HttpConnection ready to be used for uploading and downloading.
 */
private static HTTPConnection createHttpConnection(URL url)
    throws ProtocolNotSuppException
{
    // create the HTTPClient cookie, using the session cookie
    //   -> we specify "/content" as the cookie path because
    //      it is always first in content services URLs
    String sessionCookie = WsConnection.getSessionCookie();
    Cookie cookie = new Cookie("c1", sessionCookie, url.getHost(), "/content",
        null, false);

    // create a context object and add the cookie to it
    Object ctx = new Object();
    CookieModule.addCookie(cookie, ctx);
 
    // create an HttpConnection to the Document and set its context
    HTTPConnection httpCon = new HTTPConnection(url);
    httpCon.setContext(ctx);
 
    // turn off interactive mode
    httpCon.setAllowUserInteraction(false);
 
    return httpCon;
}

To upload a file, you must create a cookie for the given domain and path in order to keep the session alive while transferring data. Since you will be using the Java HTTPConnection library to upload the file, pass the cookie and a new context object to the CookieModule. This context will be associated with the session, and can then be passed to the HTTPConnection to maintain session information.

Finally, open a connection to the URL, pass the context to the connection, and turn off user interaction to prevent any HTTP user prompts. The returned HTTPConnection is then used to make a PUT call to pass the contents into the remote file.

Downloading

The process for downloading a file is similar to uploading, except that you must use the HTTPConnection.get() method. Also, there is no need to create a document; simply download the content into an HTTPResponse object, and pass the downloaded bytes into a stream.

/**
 * Downloads and prints the document content.
 */
public static void downloadDocument(Item doc)
    throws FdkException, IOException, ModuleException
{
    // get the URL attribute from the docDef Item
    NamedValue[] attrs = doc.getRequestedAttributes();
    Map attrMap = ClientUtils.namedValuesToMap(attrs);
    String docUrl = (String) attrMap.get(Attributes.URL);
    URL url = new URL(docUrl);
 
    // download the document content using HTTP
    HTTPConnection httpCon = createHttpConnection(url);
    HTTPResponse rsp = httpCon.Get(url.getFile());
 
    // check the response
    if (rsp.getStatusCode() >= 300)
    {
        System.err.println("Error: " + rsp.getReasonLine());
    }
 
    // print out the downloaded content
    System.out.println("document content:");
    InputStream content = rsp.getInputStream();
    BufferedReader in = new BufferedReader(new InputStreamReader(content));
    String data = in.readLine();
    while (data != null)
    {
        System.out.println(data);
        data = in.readLine();
    }
}

Running the Code

To run the code, connect to a Content Services instance and call the upload and download methods. Remember to log out of the Web Services instance using the logout() method of the WsConnection class.

private static WsConnection s_WsCon;

public static void main(String[] args)
{
    try
    {
        try
        {
            // URL to content services web services servlet
            String serverUrl = "http://yourserver.com:7777/content/ws";
 
            // authenticate to content services
            s_WsCon = WsConnection.login(serverUrl, "jon", "welcome1");
 
            // create the content to upload
            byte[] content = new byte[] { 't', 'e', 's', 't' };
 
            // create a document using the content
            Item doc = uploadDocument("/oracle/users/users-J/jon", "testDoc.txt",
                content);
 
            // download and show the document's contents
            downloadDocument(doc);
        }
        finally
        {
            s_WsCon.logout();
        }
    }
    catch (Throwable t)
    {
        t.printStackTrace();
    }
}