Package	mx.rpc.livecycle
Class	public class DocumentReference
Inheritance	DocumentReference Object

Language Version:

ActionScript 3.0

Product Version:

LiveCycle Data Services 3

Runtime Versions:

Flash Player 9, AIR 1.1

The DocumentReference class provides the means of referring to documents on the server, from a Flex client. A DocumentReference should be used as an input parameter to any LiveCycle operation that expects a Document input parameter. A DocumentReference will also be returned as an output parameter for any LiveCycle operation that returns a parameter of type Document.

If the document is not yet on the server, use the LiveCycle Remoting upload servlet to get the document to the server and create a DocumentReference using the URL returned by the servlet.

     import flash.net.FileReference;
     
      private function startUpload():void
     {        
       fileRef.addEventListener(Event.SELECT, selectHandler);
       fileRef.addEventListener("uploadCompleteData", completeHandler);
       try 
       {
      var success:Boolean = fileRef.browse();
       } 
       catch (error:Error) 
       {
      trace("Unable to browse for files.");
       }
     
      }
     
     private function selectHandler(event:Event):void {
       var request:URLRequest = new URLRequest("http://SERVER:PORT/remoting/lcfileupload")
       try 
       {
           fileRef.upload(request);
       } 
       catch (error:Error) 
       {
      trace("Unable to upload file.");
       }
     }
     
     private function completeHandler(event:DataEvent):void 
     {
          
       var params:Object = new Object();
       var docRef:DocumentReference = new DocumentReference();
       docRef.url = event.data as String;
       docRef.referenceType = DocumentReference.REF_TYPE_URL;
     }
     

You can also use FileReferenceList to upload multiple documents together. For example:

     import flash.net.FileReference;
     import flash.net.FileReferenceList;
     
          private function startUpload():void
          {
               pendingFiles = new Array();
               documents = new Array();
               fileRefList.addEventListener(Event.SELECT, selectHandler);
               try
               {
                   var success:Boolean = fileRefList.browse();
               }
               catch (error:Error)
               {
                   trace("Unable to browse for files.");
               }
           }
     
           private function selectHandler(event:Event):void
           {               
               var file:FileReference;                
               for (var i:uint = 0; i < fileRefList.fileList.length; i++) 
               {
                   file = FileReference(fileRefList.fileList[i]);
                   try
                   {
                       addPendingFile(file);
                   }
                   catch (error:Error)
                   {
                       Alert.show("Unable to upload file.");
                   }
               }                                       
           }        
           
           private function addPendingFile(file:FileReference):void 
           {
               trace("addPendingFile: name=" + file.name);
               var request:URLRequest = new URLRequest("http://10.60.147.127:8080/remoting/lcfileupload");
               pendingFiles.push(file);
               file.addEventListener("uploadCompleteData", completeHandler);
               file.upload(request);
           }                  
           
           private function removePendingFile(file:FileReference):void 
           {
               for (var i:uint; i < pendingFiles.length; i++) 
               {
                   if (pendingFiles[i].name == file.name) 
                   {
                       pendingFiles.splice(i, 1);
                   }
               }
           }            
     
           private function completeHandler(event:DataEvent):void
           {               
               var params:Object = new Object();
               var docRef:DocumentReference = new DocumentReference();
               docRef.url = event.data as String;
               docRef.referenceType = DocumentReference.REF_TYPE_URL;
               documents.push(docRef);
               
               var file:FileReference = FileReference(event.target);
               removePendingFile(file);  
               
               if (pendingFiles.length == 0)
               {
                   // invoke a serivce that takes a collection of documents as an argument here
                   // using the "documents" array
                  ...
     

If the document is already on the server and its file location is known, set the referenceType field to REF_TYPE_FILE and the fileRef field to the location of the file on the server. For example:

     var docRef:DocumentReference = new DocumentReference();
     docRef.fileRef = "C:/temp/file1";
     docRef.referenceType=DocumentReference.REF_TYPE_FILE;
     

If the document is already on the server and its URL is known, set the referenceType field to URL and the url field to the REF_TYPE_URL. For example:

     var docRef:DocumentReference = new DocumentReference();
     docRef.url = "http://localhost:8080/DocumentManager/1168728809000/7855483216115920647";
     docRef.referenceType=DocumentReference.REF_TYPE_URL;
     

You can also create a Document from a piece of text on the client. On the server this string will be first converted into a Byte array and then into a server side Document. By default, the server's default character set will be used for the conversion into a Byte array. If it is desired that another character set be used, it may be specified via the charsetName property of this object. For example:

     var docRef:DocumentReference = new DocumentReference();
     docRef.referenceType = DocumentReference.REF_TYPE_INLINE;
     docRef.text = "Text for my document";
     // to override server's default character set uncomment and set character set name
     // docRef.charsetName = "<name of your charset>"; 
     
     

Finally, you can create a Document from binary data available on the client. This binary data will be turned in to a server side Document. This can be used when you have small amounts of data instead of uploading the content to the server and using a URL. If you set the contentType on the reference it will be set on the document if the server side code does not figure it out on its own. For example:

     var image:ByteArray = ...
     var docRef:DocumentReference = new DocumentReference();
     docRef.referenceType = DocumentReference.REF_TYPE_INLINE;
     docRef.bytes = image;
     docRef.contentType = "image/jpg"; 
     

Flex clients will receive objects of type DocumentReference.as for LC operations that return Documents as output parameters. The DocumentReference object's referenceType will let the client know whether the content is in the DocumentReference object itself, DocumentReference.xml (the case for XML documents) or needs to be retrieved via a URL, DocumentReference.url. The DocumentReference.contentType field will let the client know the type of document.

---