mx.remoting
Class Service

class Service
extends Object

The Service class provides the client-side proxy for remote services that are available on a server and are exposed through a Flash Remoting gateway. Remote services consist of application server modules that leverage technologies such as JavaBeans, Macromedia ColdFusion Components (CFC), CFML pages, and ASP.NET web services and pages. The Service object represents a reference to a specific remote service and the functions that the service exposes. You can import the Service class using the following import statement: Import mx.remoting.Service;


Constructors
Service ( gatewayURI, logger, serviceName, conn, resp)
The Service constructor accomplishes several tasks in the course of performing its principal job, which is to create a reference to a remote service to expose the service functions. The Service constructor can also establish the gateway connection to the service, create a log to log the connection, create a reference to the connection object, and specify the Responder object that will contain the result and fault-handling methods that are called when the service returns a result or a fault condition. The gatewayURI parameter is a required parameter. If you do not specify a gateway connection URL, you must specify a null value. You can specify the gatewayURI parameter to establish the gateway connection at the same time that you create the reference to the remote service. You can specify the gatewayURI as a string as follows: 
   custService = new Service(
           "http://localhost:8300/flashservices/gateway", 
           null,
           "customerData",
           null,
           null);
The CustomerInfoExampleAPI sample application uses the flashvars parameter in the HTML file to pass the connection URL. In this case, the Service constructor for the customerData service specifies only the serviceName parameter in creating Service object. The following example shows both the flashvars parameter that specifies the gateway connection in the CustomerInfoExampleAPI.html file and the Service constructor for the customerData service in the ActionScript file: 
   <param name="flashvars" value="gatewayUrl=http://localhost:8300/flashservices/gateway/"/>

   custService = new Service(
       "", // set using flashvars to http://localhost:8300/flashservices/gateway
       null,
       "customerData",
       null,
       null);
The gatewayURI parameter allows for sharing the connection so that if a connection already exists for the specified gatewayURI parameter, the application will share it. The second parameter, which is required, is a Log object that allows you to log the connection. If you do not want to create a log, you can specify a null value for the Log parameter. For more information about the Log object, see Log class. The serviceName parameter is required. It is a string that specifies the name of the service that you want to access and for which you are creating a reference. In the previous example, the name of the service to which the CustomerInfoExampleAPI application connects is customerData. The conn parameter allows you to use an existing connection to connect to the remote service. For example, the Service constructor for employee in the following example uses the connection created by the cust Service constructor to access a second remote service, employeeData. 
   var cust:Service = new Service( "http://localhost:8300/flashservices/gateway", null, "customerData", null, custDataResp ); 
   
   var employee:Service = new Service( null, null, "employeeData", cust.connection, empDataResp );
The gatewayURI and the connection parameters are mutually exclusive. If you specify a connection parameter, it always takes precedence over the gatewayURI parameter. If you do not specify a gateway using the gatewayURI parameter, the connection parameter, or an HTML flashvars parameter, you will receive an error. The resp parameter allows you to specify the Responder object that contains the result and fault handling methods that receive control when the service returns a result or a fault condition. For more information, see RelayResponder class. After successfully creating a new Service object, you can access the name of the service in the name property and the connection for the service in the connection property. For more information on the Connection class, see Connection class. For information on calling service functions, see Calling service functions. For a complete example that connects to and accesses a remote service using the Service object, see Using the Flash Remoting ActionScript API in the CustomerInfoExampleAPI application. For an example that connects to and accesses a remote service using the RemotingConnector, see "Using the RemotingConnector in the CustomerInfoExampleCon application". For information on troubleshooting your Flash Remoting application, see The NetConnection Debugger.


Properties
staticversion: String
 Component version.
      connection: Connection  [ Read-Only]
Read only accessor for the associated connection.
      name: String  [ Read-Only]
Returns the the name of the service which can be a Java classname/JNDI location or a ColdFusion component
      responder: Responder  [ Read-Only]
Responder associated with this service.


Constructor Detail

Service

Service( gatewayURI, logger, serviceName, conn, resp)

The Service constructor accomplishes several tasks in the course of performing its principal job, which is to create a reference to a remote service to expose the service functions. The Service constructor can also establish the gateway connection to the service, create a log to log the connection, create a reference to the connection object, and specify the Responder object that will contain the result and fault-handling methods that are called when the service returns a result or a fault condition. The gatewayURI parameter is a required parameter. If you do not specify a gateway connection URL, you must specify a null value. You can specify the gatewayURI parameter to establish the gateway connection at the same time that you create the reference to the remote service. You can specify the gatewayURI as a string as follows: 
   custService = new Service(
           "http://localhost:8300/flashservices/gateway", 
           null,
           "customerData",
           null,
           null);
The CustomerInfoExampleAPI sample application uses the flashvars parameter in the HTML file to pass the connection URL. In this case, the Service constructor for the customerData service specifies only the serviceName parameter in creating Service object. The following example shows both the flashvars parameter that specifies the gateway connection in the CustomerInfoExampleAPI.html file and the Service constructor for the customerData service in the ActionScript file: 
   <param name="flashvars" value="gatewayUrl=http://localhost:8300/flashservices/gateway/"/>

   custService = new Service(
       "", // set using flashvars to http://localhost:8300/flashservices/gateway
       null,
       "customerData",
       null,
       null);
The gatewayURI parameter allows for sharing the connection so that if a connection already exists for the specified gatewayURI parameter, the application will share it. The second parameter, which is required, is a Log object that allows you to log the connection. If you do not want to create a log, you can specify a null value for the Log parameter. For more information about the Log object, see Log class. The serviceName parameter is required. It is a string that specifies the name of the service that you want to access and for which you are creating a reference. In the previous example, the name of the service to which the CustomerInfoExampleAPI application connects is customerData. The conn parameter allows you to use an existing connection to connect to the remote service. For example, the Service constructor for employee in the following example uses the connection created by the cust Service constructor to access a second remote service, employeeData. 
   var cust:Service = new Service( "http://localhost:8300/flashservices/gateway", null, "customerData", null, custDataResp ); 
   
   var employee:Service = new Service( null, null, "employeeData", cust.connection, empDataResp );
The gatewayURI and the connection parameters are mutually exclusive. If you specify a connection parameter, it always takes precedence over the gatewayURI parameter. If you do not specify a gateway using the gatewayURI parameter, the connection parameter, or an HTML flashvars parameter, you will receive an error. The resp parameter allows you to specify the Responder object that contains the result and fault handling methods that receive control when the service returns a result or a fault condition. For more information, see RelayResponder class. After successfully creating a new Service object, you can access the name of the service in the name property and the connection for the service in the connection property. For more information on the Connection class, see Connection class. For information on calling service functions, see Calling service functions. For a complete example that connects to and accesses a remote service using the Service object, see Using the Flash Remoting ActionScript API in the CustomerInfoExampleAPI application. For an example that connects to and accesses a remote service using the RemotingConnector, see "Using the RemotingConnector in the CustomerInfoExampleCon application". For information on troubleshooting your Flash Remoting application, see The NetConnection Debugger.

Parameters
    gatewayURI: String - A string specifying the gateway that should be created or used from the current pool. If you do not specify a gateway connection with this parameter, you must specify an empty string like "".
    logger: Log - A Log object to which debugging messages are sent. If you do not specify a Log, you must specify a null value.
    serviceName: String - A string specifying the name of the service to access.
    conn: Connection - The Connection object to use to connect to the service. If specified, takes precedence over gatewayURI. If you do not specify a Connection object, you must specify a null value.
    resp: Responder - A Responder object that handles the callbacks for service function calls and relays the result or fault condition to the specified object and methods. If you do not specify a Responder object, you must specify a null value.

Example
The following example, which excerpts the CustomerInfoExampleAPI sample application. The example creates the custService object as part of the CustomerInfoForm class, which extends the Form class.The application first imports the Flash Remoting classes that it needs to connect to the service, invokes a service function, and handles the result, or possibly the error, that the function returns. The call to super() invokes the superclass (Form) constructor, to perform superclass initialization. The call to mx.remoting.debug.NetDebug.initialize() initializes debug support prior to creating the gateway connection or performing any other debugging or Flash Remoting operations. Specifying the full class name (mx.remoting.debug.NetDebug), imports the class and initializes debugging support in a single line. Notice that there is no import statement for the NetDebug class. The import statement would simply enable you to call a method of the class using the shorthand method name NetDebug.initialize(), without the package portion of the class name. The Service constructor connects to a ColdFusion gateway (http://localhost:8300/flashservices/gateway) and creates a proxy (custService) for the customerData service. The Service constructor does not specify a Log for the connection (first null), an existing connection (second null) to use, or a RelayResponder object (third null) for the Service. The CustomerInfoForm() constructor next calls the getCategories() function of the custService service to obtain a list of categories. This call returns the PendingCall object, pc. The last line sets the responder property of pc to the RelayResponder object, which specifies the methods (onCategoryData() and onCategoryFault()) to receive the result and fault condition (onCategoryFault()) outcomes of the service function call. To see the full application, see Using the Flash Remoting ActionScript API in the CustomerInfoExampleAPI application. 
   import mx.remoting.Service;
   import mx.services.Log;
   import mx.rpc.RelayResponder;
   import mx.rpc.FaultEvent;
   import mx.rpc.ResultEvent;
   import mx.remoting.PendingCall;
   import mx.remoting.RecordSet;
   import mx.screens.Form;
   //
   class CustomerInfoForm extends Form {
     function CustomerInfoForm() {
       super();
       mx.remoting.debug.NetDebug.initialize(); // initialize the NCD
       custService = new Service(
         "http://localhost:8300/flashservices/gateway",
          null,
          "customerData",
          null,
          null);
        // load category combo
        var pc:PendingCall = custService.getCategories(); // get all categories
        pc.responder = new RelayResponder(this, "onCategoryData", 
          "onCategoryFault" );
     }
     
     private var custService:Service;
   }


Property Detail

connection

connection: Connection  [ Read-Only]

Read only accessor for the associated connection. This returns any existing connections that have been previously created with the given uri

name

name: String  [ Read-Only]

Returns the the name of the service which can be a Java classname/JNDI location or a ColdFusion component

responder

responder: Responder  [ Read-Only]

Responder associated with this service.

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/Service.html