Data service tag properties

concurrency

The default value for the concurrency property. This property indicates how to handle multiple calls to the same method. The following values are permitted:

• single Only a single request 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 value.

fault

The default value for the handler for the fault event. This property specifies ActionScript code that runs when an error occurs.

When no event handler is specified for faults at the web service operation level or remote object service method level, the faults are passed to the fault event at the service level; for more information, see Handling asynchronous calls to data services.

The following example tag specifies a handler for the fault event of a web service:

<!-- The specified WSDL URl is not functional. -->
<mx:WebService id="myWebService"
   wsdl="/ws/WeatherService?wsdl" fault="showErrorDialog(event.fault.faultstring)"/>

id

The instance name that you use to refer to the web services, HTTP service, or remote object service in ActionScript code.

protocol

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.

result

The default value for the handler for the result event. This property specifies ActionScript code that runs when a result object is available.

showBusyCursor

When set to true, a busy cursor is displayed while a service is executing. The default value is false. You cannot control showBusyCursor for individual operations or methods. As a workaround, you can use different services for the same WSDL document or class.

useProxy

For web services and HTTP services, you can bypass the Flex proxy by setting the useProxy property to false in an <mx:WebService> tag or <mx:HTTPService> tag, depending on the value of the corresponding <proxy-use-policy> tag in the <web-service-proxy> tag or <http-service-proxy> tag in the flex-config.xml file.

endpoint

A specific alternative gateway endpoint. This property overrides the default (global) gateway endpoint in the <amf-gateway> tag of the <remote-objects> tag in the flex-config.xml file.

You cannot use the type property if you change the endpoint to a non-Flex AMF gateway.

The endpoint value can be a fully qualified path or a relative path. For a path that starts with @ContextRoot(), the endpoint is relative to the web application's context root. For a path that starts with a slash (/), the endpoint is prepended to the protocol, host, and port of the Flex application.

id

The instance name that you use to refer to the Java object in ActionScript code.

named

A named service that is specified in the flex-config.xml file. If you use the named property, you cannot use the source property.

source

Required for unnamed services; the source of the object.

type

The type of object access. The default type is stateless-class. The following values are permitted:

• stateless-class A plain old Java object (POJO) or JavaBean; each method call creates a new object instance. This is the default value.
• stateful-class A POJO or JavaBean; the object state is maintained and each method call is made on the same object instance.
• servlet A Java servlet. The servlet type is used with the session servlet; for more information, see Using a service with binding, validation, and event handlers.

The type property is only supported for the Flex AMF gateway, and cannot be used for legacy endpoints (gateways).

For named services, you can specify type in the flex-config.xml file. If you specify type in both places, the values must match or an error is reported.

load

The value of the event handler for successful web service initialization.

service

A specific service name. Use when a WSDL document contains more than one service definition.

port

A specific port name. Use when a WSDL document contains more than one port definition. You only need to use a port property when a WSDL <service> tag contains more than one <port> tag that uses SOAP. Many web services contain ports that use HTTP Get and HTTP Post in addition to SOAP. For example, you would not need to specify a port for the following service because only one port uses SOAP:

<service name="Shakespeare">
   <port name="ShakespeareSoap" binding="s0:ShakespeareSoap">
      <soap:address location="http://www.xmlme.com/WSShakespeare.asmx" />
   </port>
   <port name="ShakespeareHttpGet" binding="s0:ShakespeareHttpGet">
      <http:address location="http://www.xmlme.com/WSShakespeare.asmx" />
   </port>
   <port name="ShakespeareHttpPost" binding="s0:ShakespeareHttpPost">
      <http:address location="http://www.xmlme.com/WSShakespeare.asmx" />
   </port>
</service>

serviceName

A named service that is specified in the flex-config.xml file. If you use the serviceName property, you cannot use the wsdl property .

wsdl

The WSDL document for a web service.

contentType

The type of content for service requests. The following values are permitted:

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

method

The HTTP method for sending the request. Permitted values are GET and POST; lowercase values are converted to uppercase. The default value is GET.

resultFormat

The 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 following values are permitted:

• object The value returned is XML and is parsed as a tree of ActionScript objects. This is the default value.
• xml The value returned is XML, and it is returned as literal XML in an ActionScript XMLnode object.
• flashVars The value returned is text that contains name-value pairs, which is parsed into an ActionScript object.
• text The value returned is text, and it is left raw.

serviceName

A named service that is specified in the flex-config.xml file. If you use the serviceName property, you cannot use the url property.

url

The location of the service.

The specified URL should not contain any query arguments (question mark character (?) followed by name-value pairs).

xmlDecode

ActionScript function used to decode a service result from XML.

When resultFormat is object and if the xmlDecode property is set, Flex uses the XML that the HTTPService object returns to create an object as specified in the xmlDecode function. If it is not defined, Flex uses the default XMLDecoder to create an object.

The xmlDecode property takes an XMLNode object and should return an object. It can return any type of object, but it must return something. Returning null or undefined causes a fault.

The following example shows an <mx:HTTPService> tag that specifies an xmlDecode function:

<mx:HTTPService id="hs" xmlDecode="xmlDecoder" url="myURL" resultFormat="object" contentType="application/xml">
   <mx:request><source/>
      <obj>{RequestObject}</obj>
   </mx:request>
</mx:HTTPService>

The following example shows an xmlDecoder function:

function xmlDecoder ( myXML ) {

   // Simplified decoding logic.

   var myObj = new Object();

   myObj.name = myXML.firstChild.nodeValue;

   myObj.honorific = myXML.firstChild.attributes.honorific;   

   return myObj;

}

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 (you may have specified httpService.request = new MyClass()) and should return an XMLNode. In this example, 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.

The following example shows an <mx:HTTPService> tag that specifies an xmlEncode function:

<mx:HTTPService id="hs" xmlEncode="xmlEncoder" url="myURL" resultFormat="object" contentType="application/xml">
   <mx:request><source/>
      <obj>{RequestObject}</obj>
   </mx:request>
</mx:HTTPService>

The following example shows an xmlEncoder function:

function xmlEncoder ( myObj ) {
   return new XML("<userencoded><attrib0>MyObj.test</attrib0>
   <attrib1>MyObj.anotherTest</attrib1></userencoded>");
}