10.8 Datatype Conversions

Web services have specific simple types that are native to SOAP and other complex types that you can define. The SOAP datatypes and their ActionScript equivalencies are listed in Table 10-3.

ColdFusion also supports a QueryBean datatype, which allows you to transfer query objects as results from a web service. It is advisable, however, to create web services that will be more universally readable, such as an array. Not all consumers of web services will be able to access a QueryBean.

10.8.1 Passing Complex Datatypes to and from Web Services

Sending a complex datatype to a web service is sometimes as simple as defining it in the client-side ActionScript and passing it as an argument. An example of a web service that accepts a complex object as an argument and returns a complex object as a result is the Amazon.com web service. Unfortunately, this is not a service that is usable in different server environments. Example 10-6 works in ASP.NET and PHP environments only. The Flash Remoting gateway for Java and ColdFusion (essentially the same gateway) seems to have problems with this web service.

To make use of the Amazon.com web service, you must go to http://www.amazon.com/webservices and sign up for a free developer's kit. You are issued a developer's token that can be used as a key to use the service. Once you've done that, you are free to use their service in accordance with the licensing agreement.

One obvious use is to search Amazon.com's catalog of books. The Flash UI for Amazon.com web service example is shown in Figure 10-3. The source file, amazon.fla, can be downloaded from the online Code Depot.

Figure 10-3. The Amazon.com service using Flash Remoting

We'll use the KeywordSearchRequest( ) method of the Amazon.com web service for this example. The method accepts an object with the following properties as an argument (see the comments in Example 10-6 or the Amazon.com documentation for more information about each argument):

keyword

page

mode

tag

type

sort (optional)

devtag

The response from the service is also in the form of an object. The returned object has the following properties:

ListName

Not used for the KeywordSearchRequest( ) method.

TotalResults

Contains the total number of search results (only 10 results are returned from the service, however).

Details

An array of objects containing the details of the books returned by the search. Each element of the array is an object that contains the following properties:

URL	Manufacturer
ASIN	ImageUrlSmall
ProductName	ImageUrlMedium
Catalog	ImageUrlLarge
Artists	ListPrice
Authors	OurPrice
ReleaseDate	UsedPrice

The Artists and Authors properties are arrays as well. The code shown in Example 10-6 creates the Flash MX interface to the Amazon.com web service, which takes a complex datatype as a parameter and returns a complex datatype to the caller. Because Amazon.com implements its own pageable results, we have to implement paging in our Flash movie to be able to display all of the results. The code is commented inline.

Example 10-6. Amazon.com web service implementing a keyword search (amazon.fla)

#include "NetServices.as"

if (!connected) {
  var connected = true;
  var gatewayURL = "http://localhost/flashremoting/gateway.aspx");
  NetServices.setDefaultGatewayURL(gatewayURL);
  var gatewayConnection = NetServices.createGatewayConnection( );
  var myService = gatewayConnection.getService(
   "http://soap.amazon.com/schemas2/AmazonWebServices.wsdl", this);
}

var keywordSearchPages = 0;
var KeywordRequestArgument = new Object( );

// Initialize the object with properties and methods
KeywordRequestArgument.init = function ( ) {
  this.keyword = "";           // Search word or words
  this.page = "1";             // Page number of results
  this.mode = "books";         // Type of product we are searching
  this.tag = "myassociateID";  // Amazon.com associate ID if you have one
  this.type = "lite";          // Type is either "lite" or "heavy"
  this.devtag = "yourtaghere"; // The Amazon developer tag that is issued to you
  this.version = "2.0";        // Version number of the Amazon web service
// This ends the properties for the object

  // Methods will be stripped off before being sent to the service
  this.setPageNumber = function (page) {this.page = page.toString( );};
  this.getPageNumber = function (page) {return this.page;};
  this.setKeyword = function (keyword) {this.keyword = keyword;};

  // Call the remote service
  this.callService = function (page) { 
    this.setPageNumber(page);
    pagedisplay_txt.text = "...working";
    myService.KeywordSearchRequest(this);
  };
};

KeywordRequestArgument.init( );  // Initialize the object

previous_pb.setClickHandler("previousPage");
function previousPage ( ) {
  var page = KeywordRequestArgument.getPageNumber( );
  // Decrement the page counter, but no less than 1
  page = (page-- < 1) ? 1 : page--;
  KeywordRequestArgument.callService(page);
}

next_pb.setClickHandler("nextPage");
function nextPage ( ) {
  var page = KeywordRequestArgument.getPageNumber( );
  // Increment the page counter, but no greater than total pages
  page = (page++ >= keywordSearchPages) ? keywordSearchPages : page++;
  KeywordRequestArgument.callService(page);
}

submit_pb.setClickHandler("getResults");
function getResults ( ) {
  keywordSearchPages = 0;
  KeywordRequestArgument.setKeyword(search_txt.text);
  KeywordRequestArgument.callService("1");
}

// Turn a URL into a clickable link
function makeLink(theText,theLink) {
  return '<font color="#00cc00"><a href="' + unescape(theLink)+ '" target="_blank">' + 
theText + '</a></font>';
}

function KeywordSearchRequest_Status (error) {
  trace(error.description);
}

// Display the results
function KeywordSearchRequest_Result (result) {
  results_txt.text = "";
  if (result.TotalResults == 0) {
    pagedisplay_txt.text = "No results";
  } else {
    keywordSearchPages = Math.ceil(result.TotalResults/10);
    var temp = "";
    var totalResults = (result.TotalResults < 10) ? result.TotalResults : 10;
    for (var i=0; i < totalResults; i++) {
    temp += makeLink(result.Details[i].ProductName, result.Details[i].Url)+
            "<br>";
    temp += "by " + result.Details[i].Authors.join(", ") + "<br>";
    temp += "List price: " + result.Details[i].ListPrice + "<br>";
    temp += "Amazon price: " + result.Details[i].OurPrice + "<br>";
    temp += result.Details[i].Manufacturer + ": " +
            result.Details[i].ReleaseDate + "<br>";
    temp += "<br>";
    }
    results_txt.htmlText = temp;
    pagedisplay_txt.text = "Page " + KeywordRequestArgument.getPageNumber( ) +
       " of " + keywordSearchPages;
  }
}

In this case, we attach the parameters required for the web service as properties of a generic Object, KeywordRequestArgument. The parameters are handled by the Flash Remoting adapter on the server and translated into the proper SOAP datatypes by the application server. An object is returned to the Flash movie and is parsed and displayed in the KeywordSearchRequest_Result( ) function.

Example 10-6 uses the ASP.NET gateway. No server-side code is necessary. For PHP, the code should work as written (because it passes the parameters to the service as properties of an object), provided you update the gateway URL to point to the PHP gateway.

I hope that Macromedia makes the future versions of Flash Remoting more consistent across server implementations so that services such as Amazon.com can be used by ColdFusion MX and J2EE servers as well.

10.8.2 Passing Simple Arrays to Web Services

Web services can supply many different types of results to consumers of those services. Many web services pass simple strings or simple values. In Example 10-6, we saw the Amazon.com web service, which passes a complex object, making it incompatible with ColdFusion MX and J2EE servers when using Flash Remoting.

An array is a basic datatype in most languages, and SOAP is no exception. The web service at http://www.communitymx.com/services/cmxfeed.wsdl passes an array of simple objects to the consumer. The web service lists articles and other content available at Community MX, a support site for Studio MX and other web technologies. The array contains objects with the following properties:

Title

Author

Category

Description

Keywords

Type_description

Url

The ActionScript code for the simple interface is shown in Example 10-7. Notice that the service method getContent( ) takes one argument: type. If you pass the argument "all", the service simply passes the latest content feed from Community MX. The interface consists of two text fields: results_txt and content_txt, with a scrollbar attached to content_txt. The source file, communitymx.fla, can be downloaded from the online Code Depot.

Example 10-7. Flash code for web service from Community MX (communitymx.fla)

#include "NetServices.as"

// Set up variables for the URL and service paths
var myURL = "http://localhost:8500/flashservices/gateway";
var servicePath = "http://www.communitymx.com/services/cmxfeed.wsdl";

// Define the custom SimpleResult class to display the results
function SimpleResult( ) { }
// Set up onResult( ) and onStatus( ) handlers as methods of SimpleResult class
SimpleResult.prototype.onResult = function (myResults) {
  results_txt.text = myResults.length + " records returned";
  var temp = "";
  for (var i=0; i < myResults.length; i++) {
    temp += makeLink(myResults[i].title,myResults[i].url) + "<br>";
    temp += "Author: " + myResults[i].author + "<br>";
    temp += "Category: " + myResults[i].category + "<br>";
    temp += "Description: " + myResults[i].description + "<br>";
    temp += "<br><br>";
    }
  content_txt.htmlText = temp;
};
SimpleResult.prototype.onStatus = function (myError) {
  results_txt.text = myError.description;
};
// Set the system status to be handled by the result status handler as well
System.onStatus = SimpleResult.prototype.onStatus;

// Make a clickable link out of the Title
function makeLink(theText,theLink) {
  var temp = '<font color="#00cc00"><a href="';
  temp += unescape(theLink);
  temp += '" target="_blank">' + theText + '</a></font>';
  return temp;
}

// Connection hasn't been initialized; create connection and service objects
if (initialized == null) {
  initialized = true;
  NetServices.setDefaultGatewayURL(myURL);
  var myConnection_conn = NetServices.createGatewayConnection( );
  var myService = myConnection_conn.getService(servicePath, new SimpleResult( ));
}

// Call the service on load
results_txt.text = "...working";
myService.getContent("all");

The content is displayed when the movie loads.

Example 10-7 uses the ColdFusion gateway. The ASP.NET version is identical, except for the path to the Flash Remoting adapter on the server. The PHP version needs to have the arguments to the service packed into an object, so replace the last line of Example 10-7 with these two lines:

var tempObj = {type:"all"};
myService.getContent(tempObj);

The J2EE and JRun versions need a JavaBean wrapper, as described earlier under Section 10.5. The JavaBean shown in Example 10-8 will work for this service after following the instructions outlined for Example 10-3 under Section 10.5.

Example 10-8. JavaBean wrapper code for the Community MX web service

// Use the same package as the wsdl2java-generated classes
package services;

public class CmxfeedBean implements java.io.Serializable {

  // Handle to the generated stub
  private services.CmxfeedCfcSoapBindingStub soap;

  // Empty constuctor
  public CmxfeedBean( ) throws java.net.MalformedURLException,
   org.apache.axis.AxisFault {
    final java.net.URL endPoint = new java.net.URL
     ("http://www.communitymx.com/services/cmxfeed.wsdl");
      soap = new services.CmxfeedCfcSoapBindingStub(endPoint,
      new org.apache.axis.client.Service( ));
    }

  // Public method to call the web services method getContent( )
  public Object[] getContent(String myArg) throws java.rmi.RemoteException {
    return soap.getContent(myArg);
  }
}