Using Flex with Enterprise Web Services

Enterprise Flex Web Services Mike Slinn http://slinnbooks.com "You can't always get what you want – but you can get what you need." -- Rolling Stones

About Mike Slinn
Author of "Flex Data Services, Eclipse and Java" ( http://slinnbooks.com )
Write for InsideRIA ( http://insideRIA.com/mike-slinn )
Independent software contractor
Recognized in US Federal court as a software expert
Java since v1.0
Flex since v1.0
Distributed computing since 1980
Graphics since 1976

Web Services
RPC and REST flavors are most common
RPC is stateless
Flex WebService component
a.k.a. "Big" web services
Heavyweight – do not use unless necessary
This talk is about RPC web services
REST is stateful
Flex HTTPService component, or
URLLoader , URLRequest and URLRequestHeader
as3httpclientlib , resthttpservice
Cloud computing is also referred to as web services (out of scope)

RPC Web Services Standards
W3C WSDL
W3C SOAP
W3C XML Schema (a.k.a. XSD)
W3C XML
A 'profile' is a specific set of versions of the above standards
WS-i Basic Profile v1.0: WSDL 1.1, SOAP 1.1 and XML Schema 1.0
Flex SDK and Flex/Flash Builder support the WS-i Basic Profile v1.0, and add support for legacy RPC-encoded web services
Flex SDK can also handle WSDL 2.0 and SOAP 1.2 namespaces
"Big" web services are very complex, I do not know of any implementation that supports all flavors and options
All implementations are therefore a subset

XML
Open standard for textual data
Verbose, requires a lot of bandwidth and expensive to deserialize
Foundation of 'big' web services
Tag: markup constructs <tag/> and <tag></tag>
Attribute: name/value pair
Element: tag with zero or more attributes, data and child elements
<blah name0="value0">ick</blah>
Data is present within open/close tags, not in attributes

XML Schema (XSD)
Schemas are more powerful than DTDs
Defines SOAP data types
Containers for element and attribute content
Uses namespaces
Provides validation constraints
Stored in WSDL and/or XSD documents
V1.0 is current

SOAP
Simple Object Access Protocol
Defines a distributed processing model
Sender, receiver, message path, etc.
Allows XML messages to be exchanged
Can use RPC and HTTP for transport

WSDL
Readily understood if you are familiar with SOAP
Schemas define complex SOAP types
Very flexible
Schemas can be complex
Test matrix can be huge
WSDL 1.1 is commonly used
WSDL 2.0 is not common

WSDL Sections

Flex SDK Components
ObjectProxy
WebService
Important undocumented SDK packages
mx.rpc.soap
mx.rpc.wsdl
http://opensource.adobe.com/svn/opensource/flex/sdk/trunk/frameworks/projects/rpc/src/mx/rpc
The Flex SDK has had few changes since v3.5 with respect to web services, in terms of supporting additional standards, bug fixes and features.
Most known bugs have been deferred (for example, Document / literal is not fully implemented)

Flex/Flash Builder Support for RPC Web Services
Apache Axis code generator
FB3/FB4 both use Apache Axis2 v1.3
Supports SOAP v1.1 and WSDL v1.1
Apache Axis2 only support doc/literal and rpc/literal
FB Axis port also supports rpc/encoded.
Generates lots of code
Flex Builder 3 uses deprecated Flex 2 classes
Attempts to support more edge cases than Flex SDK
Duplicates Flex SDK functionality but in a different way
Some Flex docs do not apply to generated code
Many known bugs are deferred
Closed source
The biggest enhancement in FB 4 is the data wizard, which wraps VOs so they can be subclassed. This feature has limited usefulness.

Flex SDK WebService component
MXML flavor automatically loads WSDL but ActionScript flavor does not
LoadEvent dispatched when WSDL is parsed
Business logic should be delayed until after WSDL is loaded
Defines a new ActionScript method for each web service operation
EndpointURI can be overridden
Mapping between SOAP types and ActionScript value objects
Uses a different mechanism than BlazeDS/LCDS ( SchemaTypeRegistry instead of RemoteClass )

Flex SDK Web Service Operation Component
An operation is a service method.
Can be called by invoking the function of the same name on the service or by calling send()
myWebService.myOperation()
myWebService.myOperation.send()
Three return formats can be obtained
object – uses SchemaTypeRegistry to map SOAP types to VOs, otherwise returns an ObjectProxy
Much of this presentation discusses how to work with this format
xml – Flex 2 XMLNodes
e4x –Flex 3 XML (easiest to work with)

SOAP Faults
Web browsers do not pass SOAP faults to the Flash player when HTTP status code 500 is set.
If possible, modify the server to set HTTP status code 200 when issuing SOAP faults so the Flash/Flex application can detect and handle the problem.

SOAP Decoder
mx.rpc.soap classes are not shown in asdoc, must examine SDK source
mx.rpsc.soap.Decoder is only briefly mentioned in other docs
Axis generated code uses deprecated Flex objects
Multiple result formats available (XML, E4X, object)
Can register SOAP type to value object mappings
Automatic conversion of SOAP response body to value object
Does not handle data in attributes unless data also provided within tags
Unwraps singly nested elements (arrays with one item and composite types)
You cannot be sure what the response type is
Operation.forcePartArrays controls array unwrapping
I have extended and customized this class for clients

Nested Anonymous complexType s
This WSDL fragment defines a nested anonymous type, which requires a custom Flex decoder to deserialize:
<xsd:element maxOccurs="1" minOccurs="0" name="myList"> <xsd:complexType> <xsd:sequence> <xsd:element maxOccurs="unbounded" minOccurs="0" name="myItem" type="MyType"/> </xsd:sequence> </xsd:complexType> </xsd:element>
The following is an equivalent WSDL declaration for a collection that does not require a custom Flex decoder
<xsd:element maxOccurs="unbounded" minOccurs="0" name="myList" type="MyType" />

Element/Attribute Data
Flex compiler considers data within tags as equivalent to attribute data
Element Data
<TextArea> <toolTip>This is a tooltip</toolTip> </TextArea>
Attribute Data
<TextArea toolTip="This is a tooltip" />
The Flex SDK does not consider the above to be equivalent
The Flex SDK's default SOAP encoder does not support attribute namespaces <myTag ns:attr1>

Mapping SOAP Types to ActionScript Value Objects
Flex SDK's SchemaTypeRegistry holds mappings
Value objects are mapped via registerClass(): SchemaTypeRegistry.getInstance().registerClass( new QName("http://example.uri", "getUserResponse"), com.domain.User);
Collections are mapped via registerCollectionClass() and also require a call to registerClass() to indicate the type of element in the collection
Only one value object type can be associated with a collection type (polymorphism is not supported)
Take care that there is an explicit reference to each VO and collection class
I usually dynamically create reference classes directly from WSDL
People often refer to collection classes as value objects, although the Flex SDK makes a distinction

Rule-based Mapping of SOAP Type to ActionScript Type
I like to use a rule-based approach to map SOAP types to ActionScript VOs and collections
Ordered set of regular expressions map fully-qualified SOAP types to fully-qualified ActionScript packages or classes
Specific rules are listed first; more general rules follow
typeMaps.push(/.*Type42Out.Entity/, "com.xyz.MyService.Entity");
typeMaps.push(/.*.(.*)/, "com.xyz.MyService.$1");

Flex SDK SOAP Encoder
Not documented, must examine SDK source
Usually not required because Flex creates XML easily
Uses deprecated Flex 2 classes
Flex 2: XMLDocument and XMLNode
Flex 3 & 4: XML and XMLList
Does not handle missing optional elements properly
Does not handle 'empty' SOAP types without elements properly
Partial support for the following XML schema features: <choice/> <all/> <union/>

Flex SDK does not support the following XML schema features
<attribute use="required"/>
<element substitutionGroup="..." unique="..." key="..." keyref="..." field="..." selector="..."/>
<simpleType> <restriction> <minExclusive> <minInclusive> <maxExclusive> <maxInclusive> <totalDigits> <fractionDigits> <length> <minLength> <maxLength> <enumeration> <whiteSpace> <pattern> </restriction> </simpleType>
<complexType final="..." block="..." mixed="..." abstract="..."/>
<any processContents="..."/>
<annotation/>

Dynamic WSDL URI and Endpoints
Do not hard-code the URI in your Flex program, or you will need to edit and recompile for deploying to each environment (dev, test, q/a, live)
Proxies often require an explicit operation endpoint
I often use an XML configuration file, loaded at runtime from the server

Runtime Configuration
For a recent project, I developed a configuration facility
XML file contains description of web services
Web services can be deployed simply by editing the file on the server
Provides a mechanism for a deployed web application to locate and configure web services.

WebService / HTTPService Configuration File
Each <httpService> and <webService> element is keyed by fqClassName .
fqClassName must match the fully qualified serviceName of the SOAP type and the subclass that manages the service.
<wsConfig> <webService fqClassName="com.mslinn.ws.SampleWebService"> <serviceName>SampleWebService</serviceName> <prefix>http://localhost:12345/</prefix> <suffix>?wsdl</suffix> <endpointURI>http://domain.com/optional:2345</endpointURI> </webService> <httpService fqClassName="com.mslinn.http.SampleHttpService"> <serviceName>SampleHttpService</serviceName> <prefix>http://localhost:23456/whatever/</prefix> </httpService> </wsConfig>

Multiple WSDL Schemas
Enterprises are likely to split complexType s into separate schemas
Provide separate namespaces for SOAP types
Flex / Axis generator handles multiple schemas well
Multiple web services can share selected schemas
Object model requires merged value objects
Flex / Axis generator does not have any provision for merging VOs
Custom Ant task can do this (using Apache CXF, WSDL4J or XPath)
I wrote one in Java that uses XPath to parse the live WSDL but hooking into the FB Axis code would require reverse engineering, which probably violates Adobe's license
A custom AIR app would not hook into the build system easily

Schema Oriented Web Services

Schema Orientation vs. Service Orientation
Enterprise web services often have more than one schema
For example, Tibco's modeling is schema-oriented, not service-oriented
Shared schemas may not be fully expressed in any given service
Value objects must be created from consolidated schemas
Value objects must be recreated when schemas evolve
A change to a schema may affect multiple services
I wrote a custom tool using AIR for a client that replaces the FB Axis generator
http://www.youtube.com/user/mslinn

Optimizing WebService and HTTPService Throughput
Use AMF to proxy requests via an AMF-enabled proxy server
Use custom destinations on a proxy server that use an AMF channel
AMF batches requests and responses
AMF provides more efficient serialization/deserialization
Benefits:
Data loads faster
Response data accessible even when the HTTP status code is not 200
See the BlazeDS docs

soapUI
Handy tool for testing web services
Very useful free version available, not open source ( http://soapui.org )
Can also test AMF, JDBC and JMS
Supports load testing of web services

Thank you!
Support an indie author!
"Flex Data Services, Hibernate and Eclipse" http://slinnbooks.com
Mike Slinn http://mslinn.com [email_address] Image courtesy Ellen Joseph

Extra Goodness / Backup material
Stuff I do not expect to have time for during this presentation

REST
Without server support, Flex only supports GET and POST HTTP methods
The BlazeDS proxy server supports additional HTTP methods (DELETE, HEAD, PUT, OPTIONS, TRACE)
Easy to roll your own REST class if no authentication is required
http://fbflex.wordpress.com/2008/06/12/a-simple-actionscript-flex-rest-client/

HTTPService and URLLoader Issues
HTTPService is a close cousin of URLLoader
HTTPService removes Basic Authentication and Digest headers for requests using GET and POST methods
URLLoader removes headers for requests using GET methods
URLLoader transforms POST requests without bodies into GET requests.

Uploading files with authentication
FileReference.upload() discards cookies and authentication headers
This is the 11th most requested Flex-related bug.
Solutions:
Upgrade to Flash 10, load the file into memory and send the file contents via a POST.
Use a proxy. Write a Tomcat filter that looks for credentials in a URL parameter and manufactures an Authentication header. The URL parameters containing the credentials would be encrypted along with everything else.

JSON
Alternative to XML
http://www.json.org/
RFC 4627
AS3CoreLib provides JSON support (and more)
Works well

http://www.micronauticsresearch.com	67
http://micronauticsresearch.com	37
http://www.micronauticsresearch.com.s3-website-us-east-1.amazonaws.com	1
http://www.linkedin.com	1

Using Flex with Enterprise Web Services

by Micronautics Research

Accessibility

Categories

Upload Details

Usage Rights

4 Embeds 106

Statistics