ASDoc

Methods | Properties | Events | Examples

mx.servicetags
Class HTTPService

All Implemented Interfaces
mx.core.MXMLObject

class HTTPService

You use the <mx:HTTPService> tag to represent an HTTPService object in an MXML file. When you call the HTTPService object's send() method, it makes an HTTP GET or POST request to the specified URL, and an HTTP response is returned. Optionally, you can pass parameters to the specified URL.

Note: Due to a software limitation, HTTPService does not generate user-friendly error messages when using GET.

MXML Syntax

The <mx:HTTPService> tag accepts the following properties:

 <mx:HTTPService
   concurrency="multiple|single|last"
   contentType="application/x-www-form-urlencoded|application/xml"
   fault="No default."
   id="No default."
   method="GET|POST"
   protocol="http|https"
   result="No default."
   resultFormat="object|xml|flashvars|text"
   serviceName="No default."
   showBusyCursor="false|true"
   url="No default."
   useProxy="true|false"
   xmlEncode="No default."
   xmlDecode="No default."
 />

These properties are discussed in Chapter 30, "Using Data Services" in Developing Flex Applications.

Note: To access an HTTP service over HTTPS from a Flex application that is served over HTTP, you must set the protocol property to https.

The <mx:HTTPService> tag can have a single <mx:request> tag under which the parameters can be specified.

Click here to view the Examples

Methods
	`cancel( ) : Void`Cancels all existing HTTP service calls.
	`clearResult( fireBindingEvent: Boolean) : Void`Set the result property of HTTPService to null.
	`clearUsernamePassword( ) : Void` Removes the current username and password from subsequent requests.
	`send( parameters: Object) : Object` Makes an HTTP GET or POST request to the specified URL.
	`setUsernamePassword( username: String, password: String) : Void` Sends the username and password as part of each request.
	`xmlDecode` ActionScript function used to decode a service result from XML.
	`xmlEncode` ActionScript function used to encode a service request as XML.

Properties
	`concurrency: String` Value that indicates how to handle multiple calls to the same service.
	`contentType: String` Type of content for service requests.
	`method: String` HTTP method for sending the request.
	`protocol: String`(MXML only, not a runtime property) Specifies the protocol to use for service requests; the value is either http or https.
	`request: Object` Object of name-value pairs used as parameters to the URL.
	`result: Object [Read-Only]` Provides access to the result of the last request.
	`resultFormat: String` Value that indicates how you want to deserialize the result returned by the HTTP call.
	`serviceName: String` Named service that is specified in the server's WEB-INF/flex/flex-config.xml file.
	`showBusyCursor: Boolean` If `true`, a busy cursor is displayed while a service is executing.
	`url: String` Location of the service.
	`useProxy: Boolean` Whether to use the Flex proxy service.

Events
`fault`	ActionScript code that runs when an error has occurred. `target` contains a reference to the component that triggered the event. `type` contains the name of the event.
`result`	ActionScript code that runs when a result object is available. `target` contains a reference to the component that triggered the event. `type` contains the name of the event.

Method Detail

cancel

cancel(
										)
										
													 : 
												Void

Cancels all existing HTTP service calls.

clearResult

clearResult(
										fireBindingEvent:
													Boolean)
										
													 : 
												Void

Set the result property of HTTPService to null. This is useful for when the result is a large object that is no longer being used.

Parameters
fireBindingEvent: Boolean - true if you want anything bound to the result to update, false otherwise. Default is true

clearUsernamePassword

clearUsernamePassword(
										)
										
													 : 
												Void

Removes the current username and password from subsequent requests.

send

send(
										parameters:
													Object)
										
													 : 
												Object

Makes an HTTP GET or POST request to the specified URL.

Parameters
parameters: Object - Parameters to pass to the specified URL. This parameter is optional and overrides whatever is already set in the <CODE>request</CODE> property.

Returns
HTTP call that can be used for tracking multiple requests.

setUsernamePassword

setUsernamePassword(
										username:
													String, password:
													String)
										
													 : 
												Void

Sends the username and password as part of each request. The username and password data is not sent via the standard Authorization header. Instead, it is sent to the proxy servlet, which creates the header.

Parameters
username: String - Username to send.
password: String - Pasword to send.

xmlDecode

xmlDecode(
										)

ActionScript function used to decode a service result from XML. When the resultFormat is an object and the xmlDecode property is set, Flex uses the XML that the HTTPService returns to create an Object. If it is not defined the default XMLDecoder is used to do the work.

The function referenced by the xmlDecode property must take an XMLNode object as a parameter and should return an Object. It can return any type of object, but it must return something. Returning null or undefined causes a fault.

xmlEncode

xmlEncode(
										)

ActionScript function used to encode a service request as XML. When the contentType of a request is application/xml and the request object passed in is an Object, Flex attempts to use the function specified in the xmlEncode property to turn it into XML. If the xmlEncode property is not set, Flex uses the default XMLEncoder to turn the object graph into XML.

The xmlEncode property takes an Object and should return an XMLNode. In this case, the XMLNode object can be an XML object, which is a subclass of XMLNode, or the first child of the XML object, which is what you get from an <mx:XML> tag. Returning the wrong type of object causes a fault.

Property Detail

concurrency

concurrency:
												String

Value that indicates how to handle multiple calls to the same service. The default value is multiple. The following values are permitted:

single Only a single request at a time is allowed on the operation; multiple requests generate a fault.
last Making a request cancels any existing request.
multiple Existing requests are not cancelled, and the developer is responsible for ensuring the consistency of returned data by carefully managing the event stream. This is the default.

contentType

contentType:
												String

Type of content for service requests.
The following values are permited:

application/x-www-form-urlencoded (default) Sends requests like a normal HTTP POST with name-value pairs.
application/xml Send requests as XML.

method

method:
												String

HTTP method for sending the request. Permitted values are GET and POST. Lowercase values are converted to upper case. The default value is GET.

protocol

protocol:
												String

(MXML only, not a runtime property) Specifies the protocol to use for service requests; the value is either http or https. The default value is the protocol over which the user loads the application. To access a service over HTTPS from a Flex application that is served over HTTP, you must set the protocol property to https.

request

request:
												Object

Object of name-value pairs used as parameters to the URL. If the contentType property is set to application/xml, it should be an XML document.

result

result:
												Object  
												[Read-Only]

Provides access to the result of the last request.

resultFormat

resultFormat:
												String

Value that indicates how you want to deserialize the result returned by the HTTP call. The value for this is based on the following:

Whether you are returning XML or name/value pairs.
How you want to access the results; you can access results as an object, text, or XML.

The default value is object. The following values are permitted:

object The value returned is XML and is parsed as a tree of ActionScript objects. This is the default.
xml The value returned is XML and is returned as literal XML in an ActionScript XMLnode object.
flashvars The value returned is text containing name=value pairs separated by ampersands, which is parsed into an ActionScript object.
text The value returned is text, and is left raw.

serviceName

serviceName:
												String

Named service that is specified in the server's WEB-INF/flex/flex-config.xml file. Use either the url property or the serviceName property, not both.

showBusyCursor

showBusyCursor:
												Boolean

If true, a busy cursor is displayed while a service is executing. The default value is false.

url

url:
												String

Location of the service. The specified URL should not contain any query parameters (? followed by name/value pairs), unless the HTTP method is GET and the <mx:HTTPService> tag contains no request parameters. Currently you can only add parameters to the URL if you set it through ActionScript, not the tag. Use either the url property or the serviceName property, not both.

useProxy

useProxy:
												Boolean

Whether to use the Flex proxy service. The default value is true. If you specify false, you must ensure that the target URL can be reached by the Flash Player. You also cannot not use named services if the useProxy property is set to false.

Examples

HttpServiceExample.mxml

<?xml version="1.0" encoding="utf-8"?>

<!-- Steps to run this example locally:
   1. Edit flex-config.xml file
      Add httpService url under whitelist config for unnamed <http-service-proxy> services, as shown below:
      
      <http-service-proxy>  
	<whitelist> 
            <unnamed>			
                <url>http://{localserver}/{your flex app folder path}/thisEmployee.xml</url>
            </unnamed>
	</whitelist>
         ............
         ............
      </http-service-proxy>
	  
   2. Copy thisEmployee.xml and save it in the same folder as HttpServiceExample.mxml.
	  
      _ _ _ _ _ _ _ _ _thisEmployee.xml_ _ _ _ _ _ _ _ _
        
        <?xml version="1.0" encoding="iso-8859-1" ?> 
            <Company label="Macromedia">
               <Branch label="Newton">
                  <Department label="Flex Doc">
                    <Name label="kapil"/>
                  </Department>
                </Branch>
            </Company>
      _ _ _ _ _ _ _ _ _ _ _ end _ _ _ _ _ _ _ _ _ _ _ _ _ 

   3. The example should run after this. -->

<!-- Simple example to demonstrate the HttpService -->
<mx:Application xmlns:mx="http://www.macromedia.com/2003/mxml" pageTitle="Employee Search Engine"
    backgroundColor="#FFFFFF">

    <mx:HTTPService id="srv" url="thisEmployee.xml"
        fault="alert(event.fault.faultstring + ' \n' + 'Invalid Employee Name');"
        result="alert('HTTPService responded!!!')">
    </mx:HTTPService>

    <mx:Script>
        <![CDATA[

           function Startsearch()
           {
              srv.send();
           }
       ]]>
    </mx:Script>

    <mx:Panel title="Employee Search Engine" height="50%" width="40%">

        <mx:Button label="Search" click="Startsearch();"/>
        <mx:Label text="Employee Explorer:"/>
        <mx:Tree dataProvider="{srv.result}" width="100%" height="100%"/>

    </mx:Panel>

</mx:Application>

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

Current page: http://livedocs.adobe.com/flex/15/asdocs_en/mx/servicetags/HTTPService.html

mx.servicetags Class HTTPService