ASDoc

mx.remoting
Class Connection

class Connection
extends NetConnection

The Connection class is a collection of methods that helps you create and use Flash Remoting connections to services. Note: The Connection class replaces the NetConnection class, which is no longer available. Macromedia recommends that you use the Service class to connect to remote services. Note: You cannot use the PendingCall or RelayResponder classes with the Connection class to handle results or fault conditions that are returned from service functions. For information on how to handle results and fault conditions with the Connection class, see Appendix A, Using NetServices and Connection Classes. You can import the Connection class using the following import statement:

   import mx.remoting.Connect;

Methods
	`addHeader( name: String, mustUnderstand: Boolean, obj: Object) : Void`Note: You do not normally use this method in Flash Remoting; it is used by the setCredentials method.
	`call( remoteMethod: String, resultObject: Object, args: Array) : Void`Invokes a command or method on the server.
	`clone( ) : Connection`Creates a new Connection object that is a clone of the current Connection object except that it does not have the headers.
	`close( ) : Void`Makes the URL previously specified with the `connect()` method into a `null` value, thereby removing the connection configuration for the remote gateway.
	`connect( url: String) : Boolean`Defines the Flash Remoting URL that is used by Flash Remoting service function calls.
	`getDebugConfig( ) : NetDebugConfig`Retrieves the NetDebug object of this Connection object`s debug-subscribed events.
	`getDebugId( ) : String`Retrieves the Connection object`s debug identifier, previously set using the `setDebugId()` method.
	`getService( serviceName: String, client: Object) : NetServiceProxy`Creates a Flash Remoting NetServiceProxy object, which allows access to application server functions.
	`setCredentials( userId: String, password: String) : Void`Submits a set of credentials that authenticates the user to the server.
	`setDebugId( id: String) : Void`Sets this Connection object`s debug identifier.
	`trace( traceObj: Object) : Void`Sends a client trace message associated with the Connection object to the NetConnection Debugger (NCD).

Properties
`static`	`version: String` Component version.

Method Detail

addHeader

addHeader(
										name:
													String, mustUnderstand:
													Boolean, obj:
													Object)
										 : Void

Note: You do not normally use this method in Flash Remoting; it is used by the setCredentials method. Adds a context header to the Action Message Format (AMF) packet structure. Every AMF packet that is sent over the connection includes this header. For more information about Action Message Format, see Understanding Action Message Format.

Parameters
    name: String - A string that triggers processing and that both Flash Remoting and the application server recognize.
    mustUnderstand: Boolean - A Boolean value that specifies whether the server must understand and process this header prior to handling any of the following headers or messages.
    obj: Object - Any ActionScript object.

call

call(
										remoteMethod:
													String, resultObject:
													Object, args:
													Array)
										 : Void

Invokes a command or method on the server. For information about handling the result of the function call, see Handling service results and errors and RelayResponder class. Note: Macromedia recommends that you use the Service object to establish a gateway connection and access remote service functions.

Parameters
    remoteMethod: String - A string in the form of serviceName.methodName where the interpretation of serviceName depends on your Flash Remoting MX application and the application server that you are using. It is the name of the service to which you are connecting.
    resultObject: Object - A responder object that specifies the result and fault handling methods for this service function call. Pass a null value for this parameter if you do not need it. The responder must have onResult and onStatus functions.
    args: Array - Optional. Any number of additional parameters that are required by the method that is being called.

Example
The following example uses the Connection class to call a Remoting web service, the results are displayed in a list called categoryList and a status message is displayed in a special status bar called statusBar:

   import mx.remoting.RecordSet;
   import mx.remoting.Connection;
   import com.mycompany.crm.utils.DisplayHandler;
   
   var con1:Connection = new Connection();
   con1.connect("http://examples.macromedia.com/flashservices/gateway/");
   con1.call("petmarket.api.catalogservice.getCategories", new DisplayHandler( statusBar, categoryList ), {locale:"en_US"});

The following class file DisplayHandler.as should be located in the com.mycompany.crm.utils classpath directory:

   
   import mx.controls.TextInput;
   import mx.controls.List;
   import mx.remoting.RecordSet;
   
   class com.mycompany.crm.utils.DisplayHandler extends Object {
   
     function DisplayHandler( disp:TextInput, lst:List ) {
       super();
       _statusBar = disp;
       _dispList = lst;
     }
   
     function onResult( result:RecordSet ):Void  {
       _dispList.dataProvider = result;
       _statusBar.text = "Got Data - " + result.length + " Record" + (result.length>1?"s":"");
     }
   
   function onStatus(stat:Object):Void {
       _statusBar.text = "DataCallFailed-" + stat.code;
     }
     private var _statusBar:TextInput;
     private var _dispList:List;
   }

clone

clone(
										)
										 : Connection

Creates a new Connection object that is a clone of the current Connection object except that it does not have the headers. Security credentials are not included in the cloned connection, so you must call the setCredentials() method to authenticate the user. Note: Macromedia recommends that you use the Service object to establish a gateway connection and access remote service functions.

Returns
A connection object that is a clone of the current connection but without headers.

Example

   import mx.remoting.Connection;
   import mx.remoting.Service;
   import mx.rpc.RelayResponder;
   
   mx.remoting.debug.NetDebug.initialize();
   
   var con1:Connection = new Connection();
   con1.setDebugId( "CategoryData - con1" );
     var catDataResp:RelayResponder = new RelayResponder( this, "onCatData", "onCatDataFault" );
   con1.connect( "http://examples.macromedia.com/flashservices/gateway/" );
   var cat:Service = new Service( null, null, "catalogservice", con1, catDataResp );
   // we want a new connection for this service to avoid batching with a
   // different debug id
   var con2:Connection = con1.clone();
   con2.setDebugId( "CategoryData - con2" );
   var cat2DataResp:RelayResponder = new RelayResponder( this, "onCatData", "onCatDataFault" );
   var categories:Service = new Service( null, null, "catalogservice", con2, cat2DataResp );

close

close(
										)
										 : Void

Makes the URL previously specified with the connect() method into a null value, thereby removing the connection configuration for the remote gateway. Subsequent attempts to call Flash Remoting MX using the Connection object fail. After using the close() method, you call connect() to define a new URL. Example
The following example uses the Connection class to call a Remoting web service. The results are displayed in a list called categoryList and a status message is displayed in a special status bar called statusBar:

   import mx.remoting.RecordSet;
   import mx.remoting.Connection;
   import com.mycompany.crm.utils.DisplayHandler;
   
   var con1:Connection = new Connection();
   con1.connect("http://examples.macromedia.com/flashservices/gateway/");
   con1.call("petmarket.api.catalogservice.getCategories", new DisplayHandler( statusBar, categoryList ), {locale:"en_US"});

The following is the class file DisplayHandler.as that should be located in the com.mycompany.crm.utils classpath directory:

   import mx.controls.TextInput;
   import mx.controls.List;
   import mx.remoting.RecordSet;
   
   class com.mycompany.crm.utils.DisplayHandler extends Object {
   
     function DisplayHandler( disp:TextInput, lst:List ) {
       super();
       _statusBar = disp;
       _dispList = lst;
     }
   
     function onResult( result:RecordSet ):Void  {
       _dispList.dataProvider = result;
       _statusBar.text = "Got Data - " + result.length + " Record" + (result.length>1?"s":"");
     }
   
     function onStatus(stat:Object):Void {
       _statusBar.text = "DataCallFailed-" + stat.code;
     }
   
     private var _statusBar:TextInput;
     private var _dispList:List;
   }

connect

connect(
										url:
													String)
										 : Boolean

Defines the Flash Remoting URL that is used by Flash Remoting service function calls. This method does not communicate with the server. When Flash Remoting executes a service function call, it makes an HTTP or HTTPS connection to the application servers. This connection persists only until the results of the call are returned to the Flash application. Note: Macromedia recommends that you use the Service object to establish a gateway connection and access remote service functions.

Parameters
url: String - The Flash Remoting URL [protocol://] host [:port] /appName The value of appName depends on the type of gateway and the configuration of Flash Remoting. For more information, see "Establishing the Flash Remoting gateway connection" on page 36. If you omit protocol://, Flash assumes you want to connect to an application server using the nonsecure HTTP protocol. The other acceptable value for protocol is https. For example, the following URLs are formatted correctly:

http://localhost:8500/flashservices/gateway
https://www.myCompany.com/myMainDirectory/securegateway.aspx/flashremoting/gateway

Returns
A Boolean value of true if the protocol part of the URL (the http: or https:) is valid; false otherwise.

Example
The following example uses the Connection class to call a Remoting web service. The connect method establishes a connection to the service gateway, the results are displayed in a list called categoryList, and a status message is displayed in a special status bar called statusBar:

   import mx.remoting.RecordSet;
   import mx.remoting.Connection;
   import com.mycompany.crm.utils.DisplayHandler;
   
   var con1:Connection = new Connection();
   con1.connect("http://examples.macromedia.com/flashservices/gateway/");
   con1.call("petmarket.api.catalogservice.getCategories", new DisplayHandler( statusBar, categoryList ), {locale:"en_US"});
   con1.close();

The following is the class file DisplayHandler.as that should be located in the com.mycompany.crm.utils classpath directory:

   import mx.controls.TextInput;
   import mx.controls.List;
   import mx.remoting.RecordSet;
   
   class com.mycompany.crm.utils.DisplayHandler extends Object {
   
     function DisplayHandler( disp:TextInput, lst:List ) {
       super();
       _statusBar = disp;
       _dispList = lst;
     }
   
     function onResult( result:RecordSet ):Void  {
       _dispList.dataProvider = result;
       _statusBar.text = "Got Data - " + result.length + " Record" + (result.length>1?"s":"");
     }
   
     function onStatus(stat:Object):Void {
       _statusBar.text = "DataCallFailed-" + stat.code;
     }
   
     private var _statusBar:TextInput;
     private var _dispList:List;
   }

getDebugConfig

getDebugConfig(
										)
										 : NetDebugConfig

Retrieves the NetDebug object of this Connection object`s debug-subscribed events. Note: This method only returns a value if the application previously called the NetDebug.initialize() method. For information on how to invoke and use the NetConnection Debugger, see The NetConnection Debugger.

Returns
A NetDebugConfig object.

Example
The following example retrieves the NetDebugConfig object from a connection named con1 and sets the httpheaders, amf, and amfheaders options:

   import mx.remoting.debug.NetDebugConfig;
   import mx.remoting.Connection;
   
   var con1:Connection = new Connection();
   var config:NetDebugConfig = con1.getDebugConfig();
   // the following settings allow http headers, amf information, and amf headers 
   // to be displayed in the NCD.
   config.app_server.httpheaders = true;  
   config.app_server.amf = true; 
   config.app_server.amfheaders = true;

getDebugId

getDebugId(
										)
										 : String

Retrieves the Connection object`s debug identifier, previously set using the setDebugId() method. Note: This method only returns a value if the application previously called the NetDebug.initialize() method. For information on how to invoke and use the NetConnection Debugger, see Chapter 5, "The NetConnection Debugger," on page 85.

Returns
A string that is the Connection object`s debug ID.

   import mx.remoting.RecordSet;
   import mx.remoting.Connection;
   import mx.remoting.debug.NetDebug;
   import com.mycompany.crm.utils.DisplayHandler;
   
   NetDebug.initialize();
   
   var con1:Connection = new Connection();
   con1.setDebugId("myDebugId");
   con1.connect("http://examples.macromedia.com/flashservices/gateway/");
   con1.call("petmarket.api.catalogservice.getCategories", new DisplayHandler( statusBar, categoryList), {locale:"en_US"});
   trace(con1.getDebugId());
   con1.close();

The following is the class file DisplayHandler.as that should be located in the com.mycompany.crm.utils classpath directory:

   import mx.controls.TextInput;
   import mx.controls.List;
   import mx.remoting.RecordSet;
   
   class com.mycompany.crm.utils.DisplayHandler extends Object {
   
     function DisplayHandler( disp:TextInput, lst:List ) {
       super();
       _statusBar = disp;
       _dispList = lst;
     }
   
     function onResult( result:mx.remoting.RecordSet ):Void  {
       _dispList.dataProvider = result;
       _statusBar.text = "Got Data - " + result.length + " Record" + (result.length>1?"s":"");
     }
   
     function onStatus(stat:Object):Void {
       _statusBar.text = "DataCallFailed-" + stat.code;
     }
   
     private var _statusBar:TextInput;
     private var _dispList:List;
   }

getService

getService(
										serviceName:
													String, client:
													Object)
										 : NetServiceProxy

Creates a Flash Remoting NetServiceProxy object, which allows access to application server functions. Note: Macromedia recommends that you use the Service object to establish a gateway connection and access remote service functions.

Parameters
serviceName: String - A string containing the name of the service to call.
client: Object - An object responder for method call result and fault outcomes.

Returns
A NetServiceProxy object that is an instance of the proxy for the network client of the specified local client and service name.

Example
The following example uses the getService() method of the Connection object named con1 to create a NetServiceProxy object. The NetServiceProxy object is then used to call the service methods:

   import mx.remoting.Connection;
   import mx.remoting.NetServiceProxy;
   
   getCategories_Result = function( results: Object ):Void {
     trace("Got Data - " + results.length + " Record" + (results.length>1?"s":""));
   }
   getCategories_Status = function( stat: Object ):Void {
     trace("DataCallFailed-" + stat.code);
   }
   var con1:Connection = new Connection();
   con1.connect("http://examples.macromedia.com/flashservices/gateway/");
   var catalogService:NetServiceProxy =
         con1.getService("petmarket.api.catalogservice", this );
   catalogService.getCategories({locale:"en_US"});

See Also
mx.remoting.Service.Service

setCredentials

setCredentials(
										userId:
													String, password:
													String)
										 : Void

Submits a set of credentials that authenticates the user to the server. The credentials are presented on all subsequent requests. You can call the setCredentials() method more than once. If the server does not authenticate the user, setCredentials() returns an error in the FaultEvent object. Note: This method only works with ColdFusion MX and JRun4 servers. For more information about authenticating a user, see Authenticating a user to the application server and Using NetServices and Connection Classes.

Parameters
userId: String - A string containing the user ID.
password: String - A string containing the user password.

Example
The following example sets the credentials of the Connection object named con1 and then calls the getCategories() method. The credentials are then changed and a call is made to the getProducts() method for all products with a categoryoid value of 5:

   import mx.remoting.Connection;
   import mx.remoting.NetServiceProxy;
   function getCategories_Result ( results: Object ):Void {
     trace("Got Categories - " + results.length + " Record" + (results.length>1?"s":""));
   }
   
   function getCategories_Status ( stat: Object ):Void {
     trace("CategoriesCallFailed-" + stat.code);
   }
   
   function getProducts_Result ( results: Object ):Void {
     trace("Got Products - " + results.length + " Record" + (results.length>1?"s":""));
   }
   
   function getProducts_Status ( stat: Object ):Void {
     trace("ProductCallFailed-" + stat.code);
   }
   
   var con1:Connection = new Connection();
   con1.connect("http://examples.macromedia.com/flashservices/gateway/");
   var catalogService:NetServiceProxy = con1.getService( "petmarket.api.catalogservice", this );
   con1.setCredentials("joe", "SeCrEt");
   catalogService.getCategories({locale:"en_US"});
   con1.setCredentials("kelly", "valleygirl");
   catalogService.getProducts({categoryoid:5});
   con1.close();

setDebugId

setDebugId(
										id:
													String)
										 : Void

Sets this Connection object`s debug identifier. Note: This method only sets the value if the application previously called the NetDebug.initialize() method. For information on how to invoke and use the NetConnection Debugger, see The NetConnection Debugger.

Parameters
id: String - A string that is the debug ID for the Connection object. This value will show up in the NCD (NetConnection Debugger) to identify this connection.

Example
The following example sets the debug ID of the Connection named con1 to the value "myDebugId". A call is then made to a Remoting service. Finally the debug ID is traced to the Output panel. You can use the filter feature in the NetConnection Debugger to show transactions only from that debug ID. The results are displayed in a list called categoryList and a status message is displayed in a special status bar called statusBar:

   import mx.remoting.RecordSet;
   import mx.remoting.Connection;
   import mx.remoting.debug.NetDebug;
   import com.mycompany.crm.utils.DisplayHandler;
   NetDebug.initialize();
   
   var con1:Connection = new Connection();
   con1.setDebugId("myDebugId");
   con1.connect("http://examples.macromedia.com/flashservices/gateway/");
   con1.call("petmarket.api.catalogservice.getCategories", new DisplayHandler( statusBar, trace(con1.getDebugId())), {locale:"en_US"});
   con1.close();

The following is the class file DisplayHandler.as that should be located in the com.mycompany.crm.utils classpath directory:

   import mx.controls.TextInput;
   import mx.controls.List;
   import mx.remoting.RecordSet;
   
   class com.mycompany.crm.utils.DisplayHandler extends Object {
   
     function DisplayHandler( disp:TextInput, lst:List ) {
       super();
       _statusBar = disp;
       _dispList = lst;
     }
   
     function onResult( result:RecordSet ):Void  {
       _dispList.dataProvider = result;
       _statusBar.text = "Got Data - " + result.length + " Record" + (result.length>1?"s":"");
     }
   
     function onStatus(stat:Object):Void {
       _statusBar.text = "DataCallFailed-" + stat.code;
     }
   
     private var _statusBar:TextInput;
     private var _dispList:List;
   }

trace

trace(
										traceObj:
													Object)
										 : Void

Sends a client trace message associated with the Connection object to the NetConnection Debugger (NCD). The trace message includes the Connection debug ID. Note: This method only sends a value if the application previously called the NetDebug.initialize() method. For information on how to invoke and use the NetConnection Debugger, see The NetConnection Debugger.

Parameters
traceObj: Object - An ActionScript object that contains the trace message to send to the NetConnection Debugger.

Example
The following example sets the DebugId of the Connection named con1 to the value "myDebugId". Before calling a method, Connection.trace() is used to send a message to the NetConnection Debugger. The results are displayed in a list called categoryList and a status message is displayed in a special status bar called statusBar:

   import mx.remoting.RecordSet;
   import mx.remoting.Connection;
   import mx.remoting.debug.NetDebug;
   import com.mycompany.crm.utils.DisplayHandler;
   
   NetDebug.initialize();
   
   var con1:Connection = new Connection();
   con1.setDebugId("myDebugId");
   con1.connect("http://examples.macromedia.com/flashservices/gateway/");
   con1.trace({level:"debug", message:"anonymous message"});
   con1.call("petmarket.api.catalogservice.getCategories", new DisplayHandler( statusBar, categoryList ), {locale:"en_US"});
   con1.close();

The following is the class file DisplayHandler.as that should be located in the com.mycompany.crm.utils classpath directory:

   import mx.controls.TextInput;
   import mx.controls.List;
   import mx.remoting.RecordSet;
   
   class com.mycompany.crm.utils.DisplayHandler extends Object {
   
     function DisplayHandler( disp:TextInput, lst:List ) {
       super();
       _statusBar = disp;
       _dispList = lst;
     }
   
     function onResult( result:RecordSet ):Void  {
       _dispList.dataProvider = result;
       _statusBar.text = "Got Data - " + result.length + " Record" + (result.length>1?"s":"");
     }
   
     function onStatus(stat:Object):Void {
       _statusBar.text = "DataCallFailed-" + stat.code;
     }
   
     private var _statusBar:TextInput;
     private var _dispList:List;
   }

Property Detail

version

static
												 version:
												String

Component version. For internal use only.

Send me an e-mail when comments are added to this page | Comment Report

Current page: http://livedocs.adobe.com/flashremoting/mx2004/actionscript_api_reference/mx/remoting/Connection.html

mx.remoting Class Connection

addHeader

call

clone

close

connect

getDebugConfig

getDebugId

getService

setCredentials

setDebugId

trace

version

mx.remoting
Class Connection