ActionScript® 3.0 Reference for the Adobe® Flash® Platform
Home  |  Show Packages and Classes List |  Packages  |  Classes  |  What's New  |  Index  |  Appendixes
mx.rpc.livecycle 

DocumentReference  - AS3 ADEP Data Services

Packagemx.rpc.livecycle
Classpublic class DocumentReference
InheritanceDocumentReference Inheritance Object

Language Version: ActionScript 3.0
Product Version: Adobe Digital Enterprise Platform Data Services for Java EE 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.events.DataEvent;
     import flash.net.FileReference;
     
      private function startUpload():void
     {        
       fileRef.addEventListener(Event.SELECT, selectHandler);
       fileRef.addEventListener(DataEvent.UPLOAD_COMPLETE_DATA, 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.events.DataEvent;
     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(DataEvent.UPLOAD_COMPLETE_DATA, 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.



Public Properties
 PropertyDefined By
  bytes : ByteArray
The client should set this field if the DocumentReference is created from binary content available on the client.
DocumentReference
  charsetName : String
If the REF_TYPE_INLINE option is being used to create a DocumentReference and the text field of this object has been set, this field may be set to determine the character set used on the server to convert the passed-in text string into a byte array.
DocumentReference
 Inheritedconstructor : Object
A reference to the class object or constructor function for a given object instance.
Object
  contentType : String
String code for content type of document.
DocumentReference
  fileRef : String
Populated when the reference type is FILE.
DocumentReference
  referenceType : int
Reference Type - either REF_TYPE_URL, REF_TYPE_FILE, or REF_TYPE_INLINE.
DocumentReference
  text : String
The client should set this field if the DocumentReference is created from a text string available on the client.
DocumentReference
  url : String
Populated when the reference type is URL.
DocumentReference
  xml : String
Populated for an XML document whose contents are passed in-line.
DocumentReference
Public Methods
 MethodDefined By
  
[static] Constructs a request to be used when uploading a document for the purposes of Remoting.
DocumentReference
  
Return the value of the specified attribute.
DocumentReference
 Inherited
Indicates whether an object has a specified property defined.
Object
 Inherited
Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter.
Object
  
Returns a list of attribute names for the DocumentReference.
DocumentReference
 Inherited
Indicates whether the specified property exists and is enumerable.
Object
  
Remove the attribute from the attribute list.
DocumentReference
  
Add an attribute to the list of attributes for the Document.
DocumentReference
 Inherited
Sets the availability of a dynamic property for loop operations.
Object
 Inherited
Returns the string representation of this object, formatted according to locale-specific conventions.
Object
 Inherited
Returns the string representation of the specified object.
Object
 Inherited
Returns the primitive value of the specified object.
Object
Public Constants
 ConstantDefined By
  REF_TYPE_FILE : uint = 2
[static] Reference to a Document on the LC server via its directory location.
DocumentReference
  REF_TYPE_INLINE : uint = 3
[static] Document contents are not referred to, but are included with this object.
DocumentReference
  REF_TYPE_URL : uint = 1
[static] Reference to a Document via a URL to LC server provided by LC DocumentManager.
DocumentReference
Property Detail

bytes

property
public var bytes:ByteArray

Language Version: ActionScript 3.0
Product Version: Adobe Digital Enterprise Platform Data Services for Java EE 3
Runtime Versions: Flash Player 9, AIR 1.1

The client should set this field if the DocumentReference is created from binary content available on the client. The referenceType should be set to REF_TYPE_INLINE in this case.

charsetName

property 
public var charsetName:String

Language Version: ActionScript 3.0
Product Version: Adobe Digital Enterprise Platform Data Services for Java EE 3
Runtime Versions: Flash Player 9, AIR 1.1

If the REF_TYPE_INLINE option is being used to create a DocumentReference and the text field of this object has been set, this field may be set to determine the character set used on the server to convert the passed-in text string into a byte array. If this field is left unset, the server's default character set is used.

contentType

property 
public var contentType:String

Language Version: ActionScript 3.0
Product Version: Adobe Digital Enterprise Platform Data Services for Java EE 3
Runtime Versions: Flash Player 9, AIR 1.1

String code for content type of document. For example, "text/xml".

fileRef

property 
public var fileRef:String

Language Version: ActionScript 3.0
Product Version: Adobe Digital Enterprise Platform Data Services for Java EE 3
Runtime Versions: Flash Player 9, AIR 1.1

Populated when the reference type is FILE.

referenceType

property 
public var referenceType:int

Language Version: ActionScript 3.0
Product Version: Adobe Digital Enterprise Platform Data Services for Java EE 3
Runtime Versions: Flash Player 9, AIR 1.1

Reference Type - either REF_TYPE_URL, REF_TYPE_FILE, or REF_TYPE_INLINE.

text

property 
public var text:String

Language Version: ActionScript 3.0
Product Version: Adobe Digital Enterprise Platform Data Services for Java EE 3
Runtime Versions: Flash Player 9, AIR 1.1

The client should set this field if the DocumentReference is created from a text string available on the client. The referenceType should be set to REF_TYPE_INLINE in this case.

url

property 
public var url:String

Language Version: ActionScript 3.0
Product Version: Adobe Digital Enterprise Platform Data Services for Java EE 3
Runtime Versions: Flash Player 9, AIR 1.1

Populated when the reference type is URL.

xml

property 
public var xml:String

Language Version: ActionScript 3.0
Product Version: Adobe Digital Enterprise Platform Data Services for Java EE 3
Runtime Versions: Flash Player 9, AIR 1.1

Populated for an XML document whose contents are passed in-line.

Method Detail

constructRequestForUpload

()method
public static function constructRequestForUpload(serverURL:String, authToken:String):URLRequest

Language Version: ActionScript 3.0
Product Version: Adobe Digital Enterprise Platform Data Services for Java EE 3
Runtime Versions: Flash Player 9, AIR 1.1

Constructs a request to be used when uploading a document for the purposes of Remoting. The returned request is to be used in conjunction with flash.net.FileReference. It should be passed in as the argument to the upload function.

Parameters

serverURL:String — the URL of the server to which you are uploading a document. For example, "http://localhost:8080" or "https://localhost:8443".
 
authToken:String — the file upload authentication token as returned by a call to getFileUploadToken of the LC.FileUploadAuthenticator RemoteObject destination. An authenticated request must have been made to the server, or single sign-on used, before a file upload is attempted.

Returns
URLRequest — a request to be used when uploading a document for the purposes of Remoting.

getAttribute

()method 
public function getAttribute(name:String):Object

Language Version: ActionScript 3.0
Product Version: Adobe Digital Enterprise Platform Data Services for Java EE 3
Runtime Versions: Flash Player 9, AIR 1.1

Return the value of the specified attribute.

Parameters

name:String — The name of the attribute.

Returns
Object

listAttributes

()method 
public function listAttributes():Array

Language Version: ActionScript 3.0
Product Version: Adobe Digital Enterprise Platform Data Services for Java EE 3
Runtime Versions: Flash Player 9, AIR 1.1

Returns a list of attribute names for the DocumentReference.

Returns
Array — A list of attribute names for the DocumentReference.

removeAttribute

()method 
public function removeAttribute(name:String):void

Language Version: ActionScript 3.0
Product Version: Adobe Digital Enterprise Platform Data Services for Java EE 3
Runtime Versions: Flash Player 9, AIR 1.1

Remove the attribute from the attribute list.

Parameters

name:String — The attribute name.

setAttribute

()method 
public function setAttribute(name:String, value:Object):void

Language Version: ActionScript 3.0
Product Version: Adobe Digital Enterprise Platform Data Services for Java EE 3
Runtime Versions: Flash Player 9, AIR 1.1

Add an attribute to the list of attributes for the Document.

Parameters

name:String — The name of the attribute.
 
value:Object — The value of the attribute.
Constant Detail

REF_TYPE_FILE

Constant
public static const REF_TYPE_FILE:uint = 2

Language Version: ActionScript 3.0
Product Version: Adobe Digital Enterprise Platform Data Services for Java EE 3
Runtime Versions: Flash Player 9, AIR 1.1

Reference to a Document on the LC server via its directory location.

REF_TYPE_INLINE

Constant 
public static const REF_TYPE_INLINE:uint = 3

Language Version: ActionScript 3.0
Product Version: Adobe Digital Enterprise Platform Data Services for Java EE 3
Runtime Versions: Flash Player 9, AIR 1.1

Document contents are not referred to, but are included with this object.

REF_TYPE_URL

Constant 
public static const REF_TYPE_URL:uint = 1

Language Version: ActionScript 3.0
Product Version: Adobe Digital Enterprise Platform Data Services for Java EE 3
Runtime Versions: Flash Player 9, AIR 1.1

Reference to a Document via a URL to LC server provided by LC DocumentManager.