Using Flex with Enterprise Web Services

1. 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

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

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

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

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

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

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

8. WSDL <ul><li>Readily understood if you are familiar with SOAP </li></ul><ul><li>Schemas define complex SOAP types </li></ul><ul><li>Very flexible </li></ul><ul><ul><li>Schemas can be complex </li></ul></ul><ul><ul><li>Test matrix can be huge </li></ul></ul><ul><li>WSDL 1.1 is commonly used </li></ul><ul><li>WSDL 2.0 is not common </li></ul>

9. WSDL Sections

10. Flex SDK Components <ul><li>ObjectProxy </li></ul><ul><li>WebService </li></ul><ul><li>Important undocumented SDK packages </li></ul><ul><ul><li>mx.rpc.soap </li></ul></ul><ul><ul><li>mx.rpc.wsdl </li></ul></ul><ul><ul><li>http://opensource.adobe.com/svn/opensource/flex/sdk/trunk/frameworks/projects/rpc/src/mx/rpc </li></ul></ul><ul><li>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. </li></ul><ul><li>Most known bugs have been deferred (for example, Document / literal is not fully implemented) </li></ul>

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

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

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

14. SOAP Faults <ul><li>Web browsers do not pass SOAP faults to the Flash player when HTTP status code 500 is set. </li></ul><ul><li>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. </li></ul>

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

16. Nested Anonymous complexType s <ul><li>This WSDL fragment defines a nested anonymous type, which requires a custom Flex decoder to deserialize: </li></ul><ul><li><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> </li></ul><ul><li>The following is an equivalent WSDL declaration for a collection that does not require a custom Flex decoder </li></ul><ul><li><xsd:element maxOccurs="unbounded" minOccurs="0" name="myList" type="MyType" /> </li></ul>

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

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

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

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

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

22. Dynamic WSDL URI and Endpoints <ul><li>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) </li></ul><ul><li>Proxies often require an explicit operation endpoint </li></ul><ul><li>I often use an XML configuration file, loaded at runtime from the server </li></ul>

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

24. WebService / HTTPService Configuration File <ul><li>Each <httpService> and <webService> element is keyed by fqClassName . </li></ul><ul><li>fqClassName must match the fully qualified serviceName of the SOAP type and the subclass that manages the service. </li></ul><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>

25. Multiple WSDL Schemas <ul><li>Enterprises are likely to split complexType s into separate schemas </li></ul><ul><ul><li>Provide separate namespaces for SOAP types </li></ul></ul><ul><ul><li>Flex / Axis generator handles multiple schemas well </li></ul></ul><ul><li>Multiple web services can share selected schemas </li></ul><ul><li>Object model requires merged value objects </li></ul><ul><ul><li>Flex / Axis generator does not have any provision for merging VOs </li></ul></ul><ul><ul><li>Custom Ant task can do this (using Apache CXF, WSDL4J or XPath) </li></ul></ul><ul><ul><ul><li>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 </li></ul></ul></ul><ul><ul><ul><li>A custom AIR app would not hook into the build system easily </li></ul></ul></ul>

26. Schema Oriented Web Services

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

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

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

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

31. Extra Goodness / Backup material <ul><li>Stuff I do not expect to have time for during this presentation </li></ul>

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

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

34. Uploading files with authentication <ul><li>FileReference.upload() discards cookies and authentication headers </li></ul><ul><li>This is the 11th most requested Flex-related bug. </li></ul><ul><li>Solutions: </li></ul><ul><ul><li>Upgrade to Flash 10, load the file into memory and send the file contents via a POST. </li></ul></ul><ul><ul><li>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. </li></ul></ul>

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