Document Transfer

Document Transfer enables the upload or download of documents attached to an RPM object such as Wbs, Scope, Asset, Resource, and others. Document transfer is implemented as an HTTP servlet, not as a WebService.

You can download or upload a document by performing a GET or POST request on the DocumentTransfer servlet providing parameters. For example:

GET http://rpmserver.com/rpm/servlet/DocumentTransfer?

ACTION=DOWNLOADUNZIPPED
&CONTEXT_NAME=WBS
&DOCUMENT_ID=EBF75A9C1E854C3B8B8DD17005032D3D
&SESSION_ID=12345678

Then you may use httpConnection.getInputStream() to download the file.

Uploads are possible via POST only. See code samples Code samplesfor details.

HTTP Parameters

The following table lists the parameters to perform HTTP GET or POST request on DocumentTransfer to upload or download a document.

Table 1. DocumentTransfer Field Description
Parameter Details
ACTION

Type: string

Description: The way document file will be downloaded

This parameter is mandatory, the following 4 values are allowed:
  • DOWNLOADZIPPED – download zipped version of the document file
  • DOWNLOADUNZIPPED – download unzipped version of the document file
  • UPLOADZIPPED – upload zipped version of the document file
  • UPLOADUNZIPPED – upload unzipped version of the document file
DOCUMENT_ID

Type: string

Description: The ID of the DocumentElement object that will be associated with a given file. You can retrieve this ID by using standard Web Services objects. This parameter is mandatory. A 32 characters maximum is allowed for its value.

SESSION_ID

Type: string

Description: Indicates the Session ID, it is created by the current server connection. It can be retrieved from the WebServices API connection. This parameter is mandatory. A 32 characters maximum is allowed for its value.

CONTEXT_NAME

Type: string

Description: Describes to which context the given Document object belongs to. This parameter is mandatory, possible values are:
  • Wbs
  • Scope
  • Client
  • Asset
  • Resource
  • Pool
FILE

Type: string

Description: Indicates the name of the file to be uploaded on the server.

CONTENT_LENGTH

Type: string

Description: Indicates the length, in bytes, of the file to be uploaded. The maximum size of a document that can be uploaded depends on database configuration.

Note: The content length might be set automatically depending on the class used to handle the upload process.

Code samples

This section provides you with a code sample intended to help you further understand the Document upload/download process. It walks you through the following Java code sample:

import java.io.BufferedInputStream;
import java.io.BufferedOutputStream;
import java.io.File;
import java.io.FileInputStream;
import java.io.FileOutputStream;
import java.net.HttpURLConnection;
import java.net.URL;

import com.ibm.rpm.document.containers.Document;
import com.ibm.rpm.document.containers.DocumentElement;
import com.ibm.rpm.document.containers.DocumentFolder;
import com.ibm.rpm.document.scope.DocumentScope;
import com.ibm.rpm.framework.LoadResult;
import com.ibm.rpm.framework.RPMException;
import com.ibm.rpm.framework.RPMObject;
import com.ibm.rpm.framework.ReloadType;
import com.ibm.rpm.framework.Result;
import com.ibm.rpm.framework.SaveResult;
import com.ibm.rpm.interfaces.Application;
import com.ibm.rpm.interfaces.ApplicationServiceLocator;
import com.ibm.rpm.interfaces.Authenticate;
import com.ibm.rpm.interfaces.AuthenticateServiceLocator;
import com.ibm.rpm.wbs.containers.Project;
import com.ibm.rpm.wbs.scope.WorkElementScope;

public class DocumentUploadDownload_CodeSample
{
    private static Authenticate authenticateInterface = null;

    private static Application applicationInterface = null;

    private static String sessionID = null;

    private static String endpointURL = "http://localhost:8080/rpm/services/";

    private static String projectName = "CodeSampleProject";

    private static String docName = "CodeSampleDoc";

    private static String documentTransferUrl = "http://localhost:8080/rpm/
    servlet/DocumentTransfer";

    private static String documentUploadPath = "C:\\Data\\";

    private static String documentDownloadPath = "C:\\";

    public static void main(String[] args)
    {
        try
        {
            System.out.println("Create Web service interfaces");

            AuthenticateServiceLocator authenticateSL = 
            nnew AuthenticateServiceLocator();
            authenticateInterface = authenticateSL
                    .getAuthenticate(new java.net.URL(endpointURL
                            + "Authenticate"));

            ApplicationServiceLocator appSL = new ApplicationServiceLocator();
            applicationInterface = appSL.getApplication(new java.net.URL(
                    endpointURL + "Application"));

            System.out.println("Login to RPM WS");
            sessionID = authenticateInterface.login("user",
                    "password", "jdbc/RPMDATASOURCE");

            createProjectWithDocument();

            uploadDocument();

            downloadDocument();

        }
        catch (Exception e)
        {
            e.printStackTrace();
        }
        finally
        {
            try
            {
                System.out.println("Logout");
                authenticateInterface.logout(sessionID);
            }
            catch (Exception e)
            {
                //do nothing
            }
        }
    }

    private static void createProjectWithDocument() throws Exception
    {

        System.out.println("Create a project");

        Project project = new Project();

        project.setName(projectName);

        WorkElementScope wbsscope = new WorkElementScope();
        DocumentScope documentScope = new DocumentScope();
        documentScope.setChildren(documentScope);
        wbsscope.setDocumentFolder(documentScope);

        SaveResult result = applicationInterface.save(sessionID, project,
                wbsscope, ReloadType.SavedResult);

        checkTaskSucessfull(result);

        project = (Project) result.getRpmObject();

        System.out.println("Reload the project with the root document folder");

        String xpath = "/Project[name='" + projectName + "']";

        LoadResult result2 = applicationInterface.loadFromXpath(sessionID,
                xpath, wbsscope);

        checkTaskSucessfull(result2);

        RPMObject[] objects = result2.getRpmObjectList();

        Project loadedProject = (Project) objects[0];
        DocumentFolder rootDocumentFolder = loadedProject.getDocumentFolder();

        System.out.println("Add a document to the project");

        Document document = new Document();
        document.setName(docName);

        rootDocumentFolder.setChildren(new DocumentElement[]
        {
            document
        });

        SaveResult result3 = applicationInterface.save(sessionID,
                loadedProject, wbsscope, ReloadType.SavedResult);

        checkTaskSucessfull(result3);

    }

    private static void uploadDocument() throws Exception
    {

        String documentId = null;
        String contextName = null;

        //To load a zipped document
        String documentName = "Test.zip";
        String action = "UPLOADZIPPED";

        //To load an unzipped document
        //String documentName = "Test.doc";
        //String action = "UPLOADUNZIPPED";

        System.out.println("Retrieve the previouly created project");

        WorkElementScope wbsscope = new WorkElementScope();
        DocumentScope documentScope = new DocumentScope();
        documentScope.setChildren(documentScope);
        wbsscope.setDocumentFolder(documentScope);

        String xpath = "/Project[name = '" + projectName + "']";

        LoadResult result = applicationInterface.loadFromXpath(sessionID,
                xpath, wbsscope);

        checkTaskSucessfull(result);

        RPMObject[] objects = result.getRpmObjectList();

        Project loadedProject = (Project) objects[0];
        DocumentFolder rootDocumentFolder = loadedProject.getDocumentFolder();
        Document doc = (Document) rootDocumentFolder.getChildren()[0];

        System.out.println("Upload the document using DocumentTransfer");

        //Document id is needed to upload the document
        documentId = doc.getID();

        //retrieve contextName from the document
        contextName = doc.getContextName();

        //Load the file into a File object
        File f = new File(documentUploadPath + documentName);
        if (f.length() > 2147483647)
        {
            throw new Exception("File is too large.");
        }

        //Create a connection
        URL url = new URL(documentTransferUrl);

        HttpURLConnection httpConnection = null;
        try
        {
            httpConnection = (HttpURLConnection) url.openConnection();

            // Enable the use of the http output stream to send the file
            httpConnection.setDoOutput(true);
            httpConnection.setDoInput(true);
            httpConnection.setUseCaches(false);
            httpConnection.setRequestMethod("POST");
            httpConnection.setRequestProperty("ACTION", action);
            httpConnection.setRequestProperty("SESSION_ID", sessionID);
            httpConnection.setRequestProperty("DOCUMENT_ID", documentId);
            httpConnection.setRequestProperty("CONTEXT_NAME", contextName);
            httpConnection.setRequestProperty("FILE", documentName);
            httpConnection.setRequestProperty("CONTENT_LENGTH", Long.toString
           (f.length()));

            httpConnection.connect();

            FileInputStream fis = new FileInputStream(f);
            BufferedOutputStream bos = new BufferedOutputStream(httpConnection
                    .getOutputStream());
            int count;
            final int BUFFER_SIZE = 2048;
            byte data[] = new byte[BUFFER_SIZE];
            int total = 0;
            while ((count = fis.read(data, 0, BUFFER_SIZE)) != -1)
            {
                bos.write(data, 0, count);
                total += count;
            }
            bos.flush();
            bos.close();
            fis.close();

            // Get the result code
            int responseCode = httpConnection.getResponseCode();

            if (responseCode != HttpURLConnection.HTTP_OK)
            {
                throw new Exception("HTTP " + responseCode + " "
                        + httpConnection.getResponseMessage());
            }
        }
        finally
        {
            if (httpConnection != null)
            {
                httpConnection.disconnect();
            }
        }
    }

    private static void downloadDocument() throws Exception
    {
        String documentId = null;
        String contextName = null;

        //To load an unzipped document
        //String action = "DOWNLOADZIPPED";

        //To load an unzipped document
        String action = "DOWNLOADUNZIPPED";

        System.out.println("Retrieve the previouly created project");

        WorkElementScope wbsscope = new WorkElementScope();
        DocumentScope documentScope = new DocumentScope();
        documentScope.setChildren(documentScope);
        wbsscope.setDocumentFolder(documentScope);

        String xpath = "/Project[name = '" + projectName + "']";

        LoadResult result = applicationInterface.loadFromXpath(sessionID,
                xpath, wbsscope);

        checkTaskSucessfull(result);

        RPMObject[] objects = result.getRpmObjectList();

        Project loadedProject = (Project) objects[0];
        DocumentFolder rootDocumentFolder = loadedProject.getDocumentFolder();
        Document doc = (Document) rootDocumentFolder.getChildren()[0];

        System.out.println("Download the document using DocumentTransfer");

        //Document id is needed to upload the document
        documentId = doc.getID();

        //retrieve contextName from the document
        contextName = doc.getContextName();

        URL url = new URL(documentTransferUrl);

        HttpURLConnection httpConnection = null;
        try
        {
            httpConnection = (HttpURLConnection) url.openConnection();
            // Enable the use of the http output stream to send the file
            httpConnection.setDoOutput(true);
            httpConnection.setDoInput(true);
            httpConnection.setUseCaches(false);
            httpConnection.setRequestMethod("POST");
            httpConnection.setRequestProperty("ACTION", action);
            httpConnection.setRequestProperty("SESSION_ID", sessionID);
            httpConnection.setRequestProperty("DOCUMENT_ID", documentId);
            httpConnection.setRequestProperty("CONTEXT_NAME", contextName);

            httpConnection.connect();

            int responseCode = httpConnection.getResponseCode();
            if (responseCode != HttpURLConnection.HTTP_OK)
            {
                throw new Exception("HTTP " + responseCode + "  "
                        + httpConnection.getResponseMessage());
            }

            String contentDisposition = httpConnection
                    .getHeaderField("Content-Disposition");
            String contentType = httpConnection.getContentType();
            System.out.println("contentType: " + contentType);

            String delimiter = "filename=\"";
            String filename = contentDisposition.substring(delimiter.length()
                    + contentDisposition.indexOf(delimiter), contentDisposition
                    .lastIndexOf('\"'));

            BufferedInputStream bis = new BufferedInputStream(httpConnection
                    .getInputStream());

            //File will be saved on disk
            File f = new File(documentDownloadPath + filename);

            BufferedOutputStream bos = new BufferedOutputStream(
                    new FileOutputStream((f)));

            int count;
            final int BUFFER_SIZE = 2048;
            byte data[] = new byte[BUFFER_SIZE];
            while ((count = bis.read(data, 0, BUFFER_SIZE)) != -1)
            {
                bos.write(data, 0, count);
            }
            bos.flush();
            bos.close();
            bis.close();

        }
        finally
        {
            if (httpConnection != null)
            {
                httpConnection.disconnect();
            }
        }

    }


    private static void checkTaskSucessfull(Result result)
    {

        if (result.isSuccessful())
        {
            System.out.println("Task sucessfull!");
        }
        else
        {

            if (result.getErrors() != null)
            {

                RPMException[] exceptions = result.getErrors();
                for (int i = 0; i < exceptions.length; i++)
                {
                    System.out.println(exceptions[i].getRpmMessage());
                }

            }
        }

    }

}