“The NetConnection class creates a bidirectional connection between a Flash Player or AIR application and a Flash Media Server application or between a Flash Player or AIR application and an application server running Flash Remoting. A NetConnection object is like a pipe between the client and the server. Use NetStream objects to send streams through the pipe.
Without Flash Media Server, you can use the NetConnection class to play video and MP3 files from a local file system or from a web server.”

As you can see, NetConnection already opens up an array of possibilities. In this specific case scenario, let me first start off by saying that I was implementing the MVC design pattern (Model View Controller). I was building a small Adobe Air Application using the Flex 4 SDK, and heavily relying on ActionScript 3.0 for most of the coding. My objective was to call remote services on three different remote servers, which would return values stating that “Yes, this server is online.” Then using the variables that it returned, set up a custom event that would fire off stating whether or not the specific server was online. My Controller would listen for the event, and upon receiving it call the respective function that would change my view to say “Let’s turn on the green button instead of the red button, because this server is online!” Here is the code to set up a connection for a specific server:

NetConnection Example

Step 1: Import related classes
You’re going to want to import flash.net packages; NetConnection, ObjectEncoding, and Responder.

Step 2: Implement variables and Constructor
Implement whatever public class variables you want, and then pass in an null IEventDispatcher object in the constructor function and call the super of that class. This is only to prevent any issues with dispatching events from this ConnectionController class.

Step 3: Create a function to check a server
Make sure the return type of this function is void. Inside this, create a private variable by declaring the var keyword, for an instance of NetConnection, and any other variables having to do with this one specific function. Declare the ObjectEncoding variable, and the connect variable in the new NetConnection variable you just declared.

Step 4: Call a function and set up dispatchers
Use _gateway.call(locationOfFunctionOnRemoteServer, new Responder(functionIfReturnValue, functionIfError), ….arguments); to make a call to the server, you can implement this line for however many functions you want to call in this one operation. After this, set up the nested functions that are called in the _gateway.call method, and fire off dispatchers with the related custom event based on a return from the server.

And there you have it, a simple way to call and get a return value from a remote server in AS3.

There’s no point doing good work if others don’t know about it or can’t understand what you did. When it comes to developing lengthy applications a well written documentation is a must. A well written documentation which compliments your project’s design shows commitment to the project and a professional feel.

In Part 1 of this tutorial we covered ANT installation. Part 2 explains the best practices for writing comments inside your project’s classes which later are read by ANT and included in the project documentation. Part 3 is the final part of this series. It will help you understand how your documentation is structured, and what can be done to customize the HTML template used by ANT to generate the documentation.
The default documentation template is the same as the one used by Adobe to document the ActionScript 3.0 language. Here is a link which I am sure you have visited before:

http://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/class-summary.html#top

Good to know:

What are HTML templates? An HTML template is a ready-made design of the HTML page. The HTML template usually include most of the source files necessary for further customizing the template. It can be edited using WYSIWYG editors such as Frontpage, Dreamweaver etc.

CSS - Cascading Style Sheets is a language used to create stylesheets in which you can describe presentation semantics, its used mainly with HTML and XHTML pages. It can also be used with Adobe Flash Builder and other. It’s a good practice to separate the styling of your project in a CSS file. This way the designer and the developer for example can work together and have a smooth workflow.

Where is the template used by ANT ?

The path to the template should look like this:
/Applications/Adobe Flash Builder 4.5/sdks/4.5.0/asdoc/templates/.

Inside the “templates” folder you will find all the components that make the HTML template. You cannot modify the template directly, but you can create a copy and assign it’s path in the ANT build script instead of using the default.

The CSS:

Through this CSS file you can assign styles to all the components that make your documentation pages. You can easily make changes to the documentation pages by modifying the styles.css (path: /Applications/Adobe Flash Builder 4.5/sdks/4.5.0/asdoc/templates/style.css).

In order to modify an element’s style you need to begin your declaration with the element’s class name. From then it’s simple. Assign the new properties as shown on the image above.

You can see the class names of the elements you would like to modify by opening the .html files of the template. Here is an example that shows where and how the class is defined for the elements and also how the stylesheet is assigned to the HTML page. If you have found a CSS stylesheet that fits your needs you could even save time and assign it instead of the default one. Then just make sure to change the class names for the elements that require customization. The global settings would stay the same.

Manipulating the HTML itself:

You could manipulate the HTML directly and change the layout of your page as well. I would recommend using Dreamweaver or other free editing software both for the CSS and the HTML. This would help you edit quickly and to see the results immediately as Dreamweaver for example has views that allow you to see the modifications live as you are making them.

Finishing up:

The range of modifications you can make to your template has almost no limits. All you need is a basic understanding of the HTML and CSS language and a good editor software.

Once you are ready to use the template or test it you need to assign it inside your build.xml file. (explained in Part 2) Here’s the example syntax:

<arg line="-templates-path '/Applications/Adobe Flash Builder 4/sdks/4.1.0/asdoc/YourTemplateName'"/>

Above is a snippet of one of CuriousMinds’ project documentation build.xml files.  As you can see there are settings editable directly through the build.xml file like the window-title and other. One of my favorite things to do is to make sure the company branding is displayed as well as the client’s. An ideal place for the Author’s name and the Company branding is the footer (line 66).

This is all there is to customizing you template. If you have any questions post and I will try to be quick to answer.

Happy coding!

NOTE: Please download attached source files from here to help you with this tutorial.

I wanted to make use of the Spring framework in my Java backend because of its flexibility and streamlined development. I wanted Hibernate integration also for data persistence to a MySQL database, which I knew Spring could provide me. It seemed to me that this stack would be the perfect combination of tools to get my application off the ground, but I wasn’t quite sure how to go about putting all these pieces together.

A little research on this topic revealed some solutions like Spring Roo with the Flex scaffolding extensions which, at least at first, seemed would glue all these components together with ease. I’m sure the Spring Roo project, once it matures a little and stabilizes, will be a viable way to generate the Java classes and Flex remoting scaffold necessary to build an application. That being said, the amount of difficulty I had in getting Spring Roo and Flex to work together was immense. I also have a huge aversion to using new tools to generate code for me that are not yet widely embraced or supported by the community at large, and which I don’t fully understand inside and out. When eventually the excrement hits the air circulation device, I want to know exactly where a system is failing and why, even if it means spending a few extra hours writing boilerplate code from scratch. I do, however, appreciate the work that Jeremy Grelle et al. have done on this project, but at present, the Roo-Flex project isn’t stable enough for my tastes. Upon realizing this, I decided to roll up my sleeves and tie the pieces together myself.

Setting up BlazeDS and Tomcat

BlazeDS is a great way to get Flex and java talking to one another. It is free, which lowers the cost barrier for you and your client, and is relatively easy to install. A popular method of getting up and running quickly is to install the BlazeDS turnkey server. This is ostensibly a Tomcat server, bundled with a bunch of very typical examples of how BlazeDS can be utilized. You can download this package from the Adobe Labs Website, or if you already have a Tomcat installation you want to develop against, you may grab the WAR file and deploy it yourself. Instructions for deploying BlazeDS, starting the server and running the examples can all be found on the website, and in the enclosed documentation.

Maven Management

Once you have a Tomcat installation and BlazeDS running in the container, we can start thinking about how to structure our java project and how to incorporate the Spring and Hibernate libraries into our project. I found SpringSource Tool Suite (STS) to be a useful IDE to develop the java side of my application. It is another Eclipse spinoff, so those familiar with this IDE will feel right at home in these environs. If you use Maven to manage your project dependencies, you can get almost everything you need by adding the requisite nodes to your pom.xml file, or by using the M2Eclipse pom editor to search for and manage your project jars. You can find instructions on installing M2Eclipse for STS on the M2Eclipse project website, and you can get SpringSource Tool Suite from here.

Once we have these pieces in place, let’s start by making a new project in STS. Choose ‘New Java Project’ from ‘File’ in the main menu of the application, and give it a name. This is the most basic java project configuration, to which we are going to add Maven support, as well as some project facets to get the resources and structure of our project tightened up. The next thing we want to do is enable dependency management with Maven. We’ll do that by right clicking on the project in our package explorer, and choosing ‘Maven -> Enable Dependency Management’. Here we are presented with some options. Because we are just creating a simple tutorial application here, I’m leaving my Group Id and Artifact Id alone, and providing a simple name and description for the heck of it. When finished with this step, a pom.xml file will be created in the project folder which we can edit to add dependencies automatically to the build path.

Project Facets

The way Eclipse organizes a project and structures a project to make it runnable in different environments is to add ‘facets’ to the project. We are going to add facets to this project now to transform this ‘vanilla’ java project into web application deployable to our Tomcat server. Again, right click on the project folder in the Package Explorer and choose ‘Properties’. You’ll see a menu item in the list called ‘Project Facets’. Choose that, and click the link to ‘Convert to faceted form…’. From the list that appears in the Project Facets Pane, select the ‘Dynamic Web Module’ checkbox, leave the ‘Java’ checkbox selected and click ‘OK’.

If you were paying attention you’ll notice that Eclipse just created a folder called ‘WebContent’, and  ‘META-INF’ and ‘WEB-INF’ folders inside that folder. This is the basic structure our java web application will take on when we export and deploy it.

Spring Dependencies

The Maven dependencies found in the attached project’s pom.xml file will give you the libraries we’re going to make use of in the next step of our tutorial. Note that there may be updates to some of these release jars by now, but avoiding the confusion of dependency compatibility is one of my goals in writing this post. Try using this list of dependencies before looking for newer releases, and save yourself some aggravation.

Feel free to copy this list directly into your project’s pom. Once we have done this, we are ready to begin building our java application’s context. You should also see that in the package explorer, our folder containing Maven Dependencies has 17 new jar files in it. These are, of course, the dependencies we’ve just added to our pom.xml.

Spring Flex Integration Jars

In addition to the above resources, we’re going to need the Flex Spring integration jars. You can get them from the following address.

Once you’ve downloaded these jars, you’ll want to make sure they get deployed along with your maven managed jars. I made a folder inside my project called ‘jar’ into which I’ve placed additional dependencies. I’ve included my jars folder here in the project archive, so you can unzip that folder into your project directory and use them. There are a few other jars in this folder. Do yourself a favor and use my jars because there are some dependencies that we have not discussed, which I spent too many hours starting and restarting my server, getting ClassDefinitionNotFound errors, and searching the web for the correct jars containing the right Classes to get this project running. Please trust me on this one. To get the items in the ‘jars’ folder to deploy properly, you want to make sure there is a corresponding entry in your ‘Web Deployment Assembly’ properties for this project. Go into the Properties for this project and select Deployment Assembly. This is where we can define mappings for deployment of our resources. If it isn’t done already, map your jar folder to ‘/WEB-INF/lib’. Our jars will now be in place when we deploy our web application.

Part I Wrap Up

Because this process of building all the components that make up this application is quite involved, I am breaking this into smaller, less daunting steps. We now have an STS project with all of the foundation to start coding our backend, and after that, to call our services from a Flex client. Be sure to check back soon for the second part of this tutorial, when we get into some of the more fun aspects of building this project.

This tutorial covers the documentation process for Ant on Adobe® Flash Builder 4.5. You will be presented with the most common ASDoc comments, their purpose and output in the generated documentation, and examples of documentation page templates and their customization process.

This is Part 2 of the Ant and Flash Builder 4.5 tutorial. If you have not yet installed and setup Ant on the standalone version of Flash Builder you can refer to Part 1. There you can get a step-by-step instruction on how to install and setup Ant.

Once you have installed and properly setup Ant on Flash Builder, it’s time to write some ASDoc comments in ActionScript® . When you generate the documentation later this code will be recognized by the Ant documentation tool and included in the generated project documentation. If you are thorough in your comments and update them along with the project’s development process, you will end up with one well written and detailed documentation and you will never forget what each class is used for.

Good to know:

•  Adobe’s help documentation is very detailed and shows all the best practices regarding the documentation process. It contains AsDoc comment examples and their formatting for all types of ActionScript classes.You can visit their documentation here.

This post is an addition which will help you instantly see what the result of the most common AsDoc comments looks like in the generated documentation. I will also cover a few mistakes that are common and if not minded can slow down your workflow or be the cause for errors which can go unnoticed by the documentation tool.

•  There is a list of HTML tags you can use to format you AsDoc comments. Bear in mind that this list of tags is limited, and that while in some sections of an AsDoc comment you can use them, in other places they are not accepted and can produce an error.
A summary of these HTML elements can be found here

•  There are two types of AsDoc comments: ActionScript comments and MXML comments.

Examples:

ActionScript comments are declared to start with  /**  character sequence and the end is declared by */. Read the example below:

 /**
*  The first sentence would be used to describe
*  the class. Next sentences only show in the
*  class' detail view.
*/

An example of an AsDoc comment used to describe a class.
output:

Above is a list of classes and their short descriptions generated by the documentation tool. The short description on the right is the first sentence in your AsDoc comment for that class.

Below is a view of the same class’ Detail Page.

• Commenting Functions:

/**
* AsDoc comment for the <code>onViewClick</code>
* method.  HTML tags <strong>can</strong> be used
* here.
* @param evt Parameter tags are
* descriptions of the parameters this
* method can take in.
*/
override protected function onViewClick(evt:MouseEvent):void{
switch(evt.currentTarget){

output:

Above is a snapshot of a Class Detail View page generated by the documentation tool.

MXML AsDoc comments:

Comments start with the <!--- characters and
end with  --> character.

This comment is placed after the xml ecoding declaration and does not require a CDATA block. You can use the same comment structure when you are commenting MXML components such as buttons, DataGrids, etc.

Here is an example of invalid implementation of the <h1>Header 1</h1> tag used where it does not belong. The text encapsulated in the wrong tag is simply omitted in the output. If these errors are not corrected you would end up with unreadable documentation.

This is an MXML AsDoc comment.
output:

Above is a snapshot of a Class Detail View page generated by the documentation tool.

Errors

My advice is when you start a new project always setup your documentation along with the project. There is nothing worse than an already built project that you have to create documentation for. When you are put in a situation where you have to document an already created project prepare to be patient and expect errors.
Here are a few common things that would cause a Build fail:

• Improperly imported classes or classes that have not been imported at all. Even though Flash Builder will run your project, and build successfully, the documentation tools will fail at that obstacle.

• Undeclared in the build file external resources and related projects. If you have read Part 1 of this tutorial, you must now know about the “-source-path”, “-doc-sources”, “-external-library-path”, and my personal favorite “-exclude-classes”. Declare all external resources because they are mentioned in your project’s code and the documentation tool would look for them, but will not find them unless you specify their paths in your buildFile.xml.

• Be careful where you place your build-file. You cannot modify the example build-file you will find in the Ant folder, but you can copy and customize it. I place my build-files directly in this location: /Applications/Adobe Flash Builder 4/sdks/4.1.0/ant/yourBuildFile.xml.

• Spark and Halo do not always mix when it comes to documentation. Below is an example of what happens when you have halo for a project theme but you have used a spark component. 
Ant build Error.

I will keep adding to this list every time I meet a new issue regarding documentation generation.

Next is Part 3 of this tutorial, where I will cover template customization. This way your documentation can take on a view and feel closer to that of your project, and I promise you good presentation always pays!

Happy coding!

Keeping up and creating a well structured documentation can sometimes be just as time-consuming as writing the application itself. That is why I use the ANT plugin for Adobe® Flash Builder 4.5. It can generate documentation structure similar to the one used for the Adobe Flex Language Reference (if you have used Adobe’s online Help/Docs/Manual), which makes it a great ASDoc tool to have when making project documentation.

For clarity, I have split this post into three parts. Part one focuses on the Ant plugin installation for Adobe® Flash Builder 4.5 and how to setup an Ant build-file.xml for your documentation project. Part 2 is the actual project documentation process for Ant on standalone Flash Fuilder 4.5. Common Glossary and output. Part 3 will cover the documentation template customization.

Good to know:

ASDoc: A command-line tool for generating API language reference documentation for your project based on specific comments that exist inside your classes.

ANT: Ant (Another Neat Tool) is a scripting tool plugin for standalone Flash Builder 4. It helps developers by automating many tasks regarding application code management. Link to ANT Manual: http://ant.apache.org/manual/index.html
build file: This is an XML file used by Ant. Consists of tags with XML-based syntax which list targets and dependencies in a script file, which is invoked from a command prompt or (as in this case) by the Ant plugin for stndalone Flash Builder 4.5.

Adobe® Flash Builder 4: Currently Adobe® Flash® Builder® 4.5 software, formerly Adobe Flex® Builder®, is an Eclipse™ based development tool for rapidly building expressive mobile, web, and desktop applications using ActionScript® and the open source Flex framework. – Adobe Website / Flash Builder 4.5

1. Ant on Flash Builder.

If you already have integrated Ant with Flash Builder skip this part.

Click to Enlarge.

1. Paste URL below in the ‘Work with:’ field. http://download.eclipse.org/releases/galileo
2. Narrow your search by typing ‘Eclipse Java’.
3. Select the Eclipse Java Development Tools check box in the list.
4. Finish the installation process and restart Flash Builder.
If your installation was successful you will see the the ANT view in Flash Builder’s ‘Other Views’ menu.

2. Generating ASDocs with Ant.

Once Ant is installed on Flash Builder you can go in FB’s ‘External Tools Configurations’ and create a new Ant  Build configuration. To get to the ‘External Tools Configurations’ dialog select Run>External Tools>External Tools Configurations.

Click to Enlarge

Next select the Ant Build configuration type and click on the ‘New’ button (top left) to create a new Ant configuration.

You can give your new Ant configuration a new name by typing in the ‘Name’ field in the configuration settings dialog.

The next step is to create a custom build file for your project and define its path in the configuration settings.

Ant’s build-files are written in XML. Each build-file must contain one project and at least one (default) target. Here is an example of a generic build-file. Tag explanations can be found here.

<?xml version="1.0"?>
<project name="Flex Ant Tasks" default="main" basedir=".">
    <target name="main" depends="clean, jar" />
    <target name="compile">
        <mkdir dir="classes" />
        <javac srcdir="src" destdir="classes"/>
    </target>
    <target name="jar" depends="compile">
        <jar destfile="lib/flexTasks.jar">
            <fileset dir="."
                     includes="flexTasks.tasks" />
            <fileset dir="classes"
                     includes="**/*.class"/>
            <fileset dir="."
                     includes="templates/**" />
        </jar>
    </target>
    <target name="clean">
        <delete dir="classes" />
		<delete file="lib/flexTasks.jar" />
        <delete>
            <fileset dir="src" includes="**/*~" defaultexcludes="false" />
        </delete>
    </target>
	<!-- - - - - - - - - - - - - - - - - -
          target: name
         - - - - - - - - - - - - - - - - - -->
    <target name="generateDocs" description="Generate Project Documentation">
    	<echo>Generating Docs</echo>
    	<exec executable="/Applications/Adobe Flash Builder 4/sdks/4.0.0/bin/asdoc" failOnError="true">
    		<arg line="-source-path '/Users/YourUsername/Documents/Adobe Flash Builder 4/AnyExternalProjectName/src' '/Users/YourUsername/Documents/Adobe Flash Builder 4/AnyExternalProjectName/libs'"/>
			<arg line="-doc-sources '/Users/YourUsername/Documents/Adobe Flash Builder 4/AnyExternalProjectName/src'"/>
			<arg line="-external-library-path '/Users/YourUsername/Documents/Adobe Flash Builder 4/AnyExternalProjectName/libs'"/>
			<arg line="-exclude-classes 'com.rng.data.customClass' 'com.rng.data.customClass2'"/>
			<arg line="-templates-path '/Applications/Adobe Flash Builder 4/sdks/4.0.0/asdoc/CM_templates'"/>
			<arg line="-main-title 'Project Documentation Title'"/>
			<arg line="-output '/Users/YourUsername/Documents/Adobe Flash Builder 4/YourDocumentedProject/outputFile'"/>
    	</exec>
    </target>
</project>

Depending on the complexity of the project you need to document, you might have to include other related projects and/or their resources. The arguments (lines 31-37 above) would give you a good example of how to do that and more.

Once you have customized your build-file remember the location where you saved it and navigate or type in the path to the file in your new Ant project’s settings view. (image below)

Now save your configuration settings and click on the ‘Targets’ tab in your configuration dialog.

Save your settings and you done with Part 1 !

If you already have written out any ASDoc comments inside your Flash Builder project work-file you can click ‘Run’ (bottom right of Configurations window). Pressing ‘Run’ will start documentation generation and you can follow its progress in the ASDoc progress console.

Next Week, Part 2 writing ASDoc Comments, Common Errors, and Exporting.

Happy Coding!

Many of the differences you’ll encounter in connecting to popular social media sites has to do with the tooling available to Flex Developers targeting the AIR runtime. Many services (Facebook, Twitter, LinkedIn to name a few) utilize OAuth 2.0 protocol for interacting with users’ data in a secure way. OAuth, in case you’re not familiar (and you will be very shortly), is “an open protocol to allow secure API authorization in a simple and standard method from desktop and web applications”. You can read the specification at http://tools.ietf.org/html/rfc5849 if you want to find out more.

OAuth basically requires that you do the following steps in order to allow the user the opportunity to grant access to your application to manage data on his or her behalf. This is an overview of the process. We will look at the specifics of how to connect to LinkedIn in a few moments, using the following basic information as a primer (or a review depending on your level of familiarity with this process).

Step 1: Register your application with the service you wish to connect to and receive a Consumer Key and Consumer Secret.

Step 2: Your application makes a request to the service to authenticate a given user. Successful completion of this step will yield a Request Token.

Step 3: The application redirects the user to the service’s sign-in and authorize page, where the user must agree to allow the app to make service calls on his behalf.

Step 4: The application, upon receiving the consent of the user, exchanges the Request Token for an Access Token. This token consists of two Strings, the token and the token secret, and will be used to “sign” (a secretive process we’ll discuss in a moment) the API requests.

Step 5: Call the resource you wish to consume (status update, personal info, etc..), using your Access Token (and a few other variables) to sign the request.

There are a numerous code libraries available for connecting to the various social media. Probably the easiest to use of these is the FacebookDesktop Object, part of the com.facebook.graph package. Right out of the box, this tool makes it quite easy to connect to Facebook’s “Graph” API, abstracting most of the ugly details of the OAuth process we’ve just enumerated. This nice little kit practically does all of the work for you, and is very simple to set up and use in your desktop app. If you need to communicate with Facebook, I highly recommend this tool.

For the purposes of this post however, I’d like to focus on LinkedIn’s API. Connecting to this service represents the other end of the difficulty spectrum in my opinion, and required quite a lot of tinkering to implement successfully. I have spent many hours refining this code. It is my hope that this tutorial will fill the enormous informational void on this topic, and help out some others where I had quite a lot of difficulty. Please grab the src folder for this sample application here. There are some functions in the source that are not included in the text of this tutorial, and I think it will serve you best to actually run this application while reading along. The tools I used to connect to LinkedIn were from the same code library I used to connect to Twitter, the OAuth lib called “oauth-as3” from iotashan http://www.iotashan.com. You can grab the latest source for this project from the following svn location: http://oauth-as3.googlecode.com/svn/trunk/. There is also a dependency introduced when we include the iotashan packages. Go ahead and grab the as3crypto swc from the following URL http://code.google.com/p/as3crypto/downloads/detail?name=as3crypto.swc and include that in the build path for your project. Alternatively, you can also grab the source from google code if you prefer to see what exactly is going on under the hood, as I have in the sample application.

So, let’s get into the code now. Admittedly, this isn’t the most impressive application I’ve ever written (from a UI standpoint), but the control flow is what we’re concerned with here, and the functional elements are pretty straightforward and informative. In order to run this application, you’ll need to register an application with LinkedIn to obtain your own Consumer Key and Consumer Secrets. I’ve indicated on lines 45 and 46 of my source where your Strings should be inserted to make your application unique from LinkedIn’s perspective. The entry point for this whole handshake process is found on line 60 in the ‘post()’ function below. This is called after you enter some comment text into the field, and hit the Submit Button on the UI.


private function post():void{
_comment = commentArea.text;
var shOb:SharedObject = SharedObject.getLocal(_sharedObName);
var tmpTok:Object = shOb.data["accessToken"];
_oauthConsumer = new OAuthConsumer(_consumerKey, _consumerSecret);
_signatureMethod = new OAuthSignatureMethod_HMAC_SHA1();
if(tmpTok){
var token:OAuthToken = new OAuthToken(tmpTok.key, tmpTok.secret);
doStatusUpdate(_comment, token);
} else {
hiOauth_CareToDance();
}
}


In this function we set up some basic variables (our OAuthConsumer and OAuthSignatureMethod_HMAC_SHA1 Objects) which we’ll need for making our requests, as well as check for the possibility that we’ve already got a valid Access Token stored in a Shared Object called ‘linkedInData.acessToken’. Let’s assume that tmpTok comes back null (line 68), and we need to go through the entire process of getting both the Request and Access Tokens from LinkedIn. We proceed to the function called ‘hiOauth_CareToDance()’ which is the point at which we’ll be requesting the Request Token.


private function hiOauth_CareToDance():void{
_requestParams = generateParams(_consumerKey);
_oauthReq = new OAuthRequest(_reqMeth, _requestTokenURL, _requestParams, _oauthConsumer, _token);
var postData:Object = _oauthReq.buildRequest(_signatureMethod, OAuthRequest.RESULT_TYPE_POST);
var urlReq:URLRequest = new URLRequest(_requestTokenURL);
urlReq.method = _reqMeth;
urlReq.data = postData;
var loader:URLLoader = new URLLoader(urlReq);
loader.addEventListener(Event.COMPLETE, onComplete);
loader.addEventListener(IOErrorEvent.IO_ERROR, onIOError);
loader.load(urlReq);


function onComplete(evt:Event):void{
loader.removeEventListener(Event.COMPLETE, onComplete); loader.removeEventListener(IOErrorEvent.IO_ERROR, onIOError);
_token = generateToken(evt.currentTarget.data);
_requestParams.oauth_token = _token; authenticate(_requestParams, _token);
}

function onIOError(evt:IOErrorEvent):void{
trace('FAIL!');
loader.removeEventListener(Event.COMPLETE, onComplete); loader.removeEventListener(IOErrorEvent.IO_ERROR, onIOError);
}
}

You’ve seen URL Requests similar to this already, but the important thing to note here is that we want to make use of our OAuthRequest Object to create the data we’ll add to the URLRequest’s ‘data’ property to send along in our POST Request. I’ve passed a few variables into the constructor of this Object to set it up, and called the instance’s buildRequest method to get back an Object containing everything LinkedIn wants to see in order to issue us a Request Token. On Event.COMPLETE we move on to the function called ‘authenticate’ after adding our token (_token) to _requestParams.oauth_token. I’ve created a convenient little utility to parse the returned data from this request and turn it into an OAuthToken Object. This function is called ‘generateToken’. In the ‘authenticate’ method we’re navigating to LinkedIn’s authentication URL, which allows the user to grant our application control to access and manipulate personal data on the user’s behalf. We also pop up a little window which gives the user a text input into which he or she will enter the 5 digit PIN number that LinkedIn’s authenticate window will supply us with. This function is called ‘popAuthWindow’.


private function authenticate(params:Object, token:OAuthToken):void{
var getReq:URLRequest = new URLRequest(_authenticateURL + '?oauth_token=' + token.key); navigateToURL(getReq, '_blank');
popAuthWindow();
}

PopAuthWindow is really quite basic as well, but the one thing to notice here is that I’ve set a variable called ‘submitCallbackFunc’ to a function called ‘authenticateCallbackFunc’ which will get called when the user clicks the ‘submit’ button in the popup window. I find this to be a little easier and more straightforward than creating a custom event for communicating between the popup and the main application, but you may have your own opinion about the cleanest way to accomplish this. This function will accept the pin number. Let’s look at this function now.


private function authenticateCallbackFunc(pin:String):void{
_requestParams.oauth_verifier = pin;
var authReq:OAuthRequest = new OAuthRequest(_reqMeth, _accessTokenURL, _requestParams, _oauthConsumer, _token);
var postData:Object = authReq.buildRequest(_signatureMethod, OAuthRequest.RESULT_TYPE_POST);
var urlReq:URLRequest = new URLRequest(_accessTokenURL);
urlReq.method = _reqMeth;
urlReq.data = postData;
var loader:URLLoader = new URLLoader(urlReq);
loader.addEventListener(Event.COMPLETE, onComplete);
loader.addEventListener(IOErrorEvent.IO_ERROR, onIOError);
loader.load(urlReq);


function onComplete(evt:Event):void{
loader.removeEventListener(Event.COMPLETE, onComplete); loader.removeEventListener(IOErrorEvent.IO_ERROR, onIOError);
_token = generateToken(evt.currentTarget.data);
_requestParams.oauth_token = _token.key;
_requestParams.oauth_token_secret = _token.secret;
var so:SharedObject = SharedObject.getLocal(_sharedObName);
so.data["accessToken"] = _token;
so.flush();
doStatusUpdate(_comment, _token);
}

function onIOError(evt:IOErrorEvent):void{
trace('FAIL!');
loader.removeEventListener(Event.COMPLETE, onComplete); loader.removeEventListener(IOErrorEvent.IO_ERROR, onIOError);
}
}

This looks an awful lot like the ‘hiOauth_CareToDance’ function we’ve already discussed, but were the ‘_token’ variable was null before (we hadn’t yet gotten our Request Token) we are now going to have the data returned from our call to the Request Token resource. In this step, we are ostensibly trading the Request Token for an Access Token. We make use of our handy OAuthRequest Object once again to put together the variables and the signature needed to gain access to LinedIn’s Access Token resource, and populate the URLRequest’s data property with our return from the buildRequest method. On our Complete Event, we will again be given another bit of data from which we can parse our ‘oauth_token’ and ‘oauth_token_secret’. At this point we have been fully authenticated, and have everything we need to call the actual API resources we might wish to utilize in our application. So, knowing this we can finally call the status update resource, and submit our comments we had typed into our comments text input. We do this in the ‘doStatusUpdate’ method.


private function doStatusUpdate(comment:String, tok:OAuthToken):void{
if(!_requestParams){
_requestParams = generateParams(_consumerKey);
delete _requestParams.oauth_token_secret;
delete _requestParams.oauth_verifier;
var oauthGen:OAuthRequest = new OAuthRequest(_reqMeth, _statusUpdateURL, _requestParams, _oauthConsumer, tok);
var header:URLRequestHeader = oauthGen.buildRequest(_signatureMethod, OAuthRequest.RESULT_TYPE_HEADER);
var urlReq:URLRequest = new URLRequest(_statusUpdateURL);
urlReq.method = _reqMeth;
urlReq.requestHeaders.push(header);
urlReq.contentType = 'text/xml';
urlReq.data = generateLinkedInStatusXML(comment);
var loader:URLLoader = new URLLoader(urlReq);
loader.addEventListener(Event.COMPLETE, onComplete);
loader.addEventListener(IOErrorEvent.IO_ERROR, onIOError);
loader.load(urlReq);

function onIOError(evt:IOErrorEvent):void{
// if we hit this.. our token must be expired..
hiOauth_CareToDance();
}
}


We see some familiar elements in this, such as the OAuthRequest and the URLRequest variables, but you’ll also notice that we have introduced a URLRequestHeader in this function which we did not have previously. The reason for this is that we are now transmitting two necessary pieces of data over the wire, not just one. We have to supply our Access Token so that we can demonstrate to LinkedIn’s servers that we are legit, but we also want to send some data to update our status at the same time. This was a little tricky for me to figure out, so I’m hoping that this demo makes even one developer’s life a little easier (ten would be even better). In order to do this, we will again build the OAuth signature with the OAuthRequest, but since we are going to want to use the data property of our URLRequest for the status update XML, we need to change the mode of our OAuthRequest to OAuthRequest.RESULT_TYPE_HEADER. You’ll notice this on line 89 of the sample application. When we change the request type to header, we get back a URLRequestHeader instead of a generic Object. This we can then push into our requestHeaders array. LinkedIn is able to deal with this accordingly, and will verify the validity of this request based on the header, and not the data of our request as we had done previously. As for the data in this step (the actual status comment), I have created a very basic ‘generateLinkedInStatusXML’ function which creates the most basic status update markup from our comment input text. You can do more with this data if you so desire. Please refer to the LinkedIn API reference pages for more information on this.

In addition, make sure you set the content type of your URLRequest to ‘text/xml’ or you will not have success in making this call (yet another trap I fell into during this arduous process). There are also 2 lines of code deleting certain items from the _requestParams data before we make this request. These 2 variables were necessary in previous steps of the OAuth authentication process, but which we no longer need now that we have the Access Token. Don’t pay too much attention to these. I believe you can leave those intact, and it will have zero effect on the success of this call.

OK, with a little bit of luck this request will come back successfully and our application will alert us to the fact that our status has been updated. Hop on over to your LinkedIn profile and verify that the message did make it onto your wall (or whatever they call it in LinkedIn parlance).

Congratulations! You have just successfully navigated the tedious OAuth handshake, and are now able to build out a more useful and full featured application based on this new knowledge.

Adobe’s newest attempt at reconciling its past branding snafus, is to name their new flagship IDE ‘Flash Builder’ which for me just seemed like a bad mashup of its progenitors’ names. And this at a time when the development community had fully embraced the Flex application paradigm and branding, and to a great extent, so had the better informed end users of Flex applications. I personally thought that Flex Builder had a much more appealing ring to it as well, but hey, that’s just my personal opinion.

But how easy it is to be critical, and from what I can tell (despite the obligatory growing pains) this release is going to be a great big step forward for our team. Allow me to elaborate some..

We at curious minds have recently been working on some pretty snazzy AIR apps over the last few months, and in the process gotten very adept at skinning our components and integrating our designers’ work quickly and effectively. (There are a few of our  blog posts relating to these topics that are quite informative if you are interested). According to Adobe, Catalyst is going to give us even more flexibility (not a pun) and better integration than before. Our designers are going to be able to create Flex apps directly in Catalyst, and our developers can import them and get down to business integrating the UIs with data and application logic. Finally, we’ll actually be able to work in the same environment, and on the same app simultaneously! I know that for certain developers (myself very much included), this is going to make life a great deal easier, allowing us to focus on the things that we are actually good at doing. This is probably the best feature of Catalyst as I see it. The fact that the work will now flow both directions between designers and developers, instead of the ‘uni-directional’ limitation that seems to pervade our current system.

Another feature that I’m completely gaga over in ‘Gumbo,’ is the integrated network traffic monitor. What a huge help this tool is going to be in the development/debugging process! With inline tree views of XML and AMF server response data, this HTTP monitor is going to cut a lot of the nasty trace style debugging right out. Also, being able to jump directly to the line in your code that originated the RPC request is a great feature of this tool.

All in all, I am really excited about diving into the new IDE. I’ll post up a full report once we get a little better situated with our new software, and as always, look for great tutorials on the new generation of Adobe design/development tools.

Font Book on mac is a great app. Using the app’s ability to intropect on the font, you can see all of the information in each font on your computer. The most important information you can get out of Font Book is the full font name attribute. The key here is to embed the full font name attribute in the flex application. Just like this:

@font-face
{
     src: url(‘path/to/embed.swf’);
     fontFamily:”Helvetic Neue LT Com Bold 77″;
} 

The important thing here is that if you arre unsure of what font faces are included in any particular font, just use the full font name alone, and dont mess with anything else. 

For Flex Builder 3 apps, we like to use the Flash Embed method of getting the font transcoded into the Flex App. The resulting file size is much lower. Just be sure to embed only the characters that you are going to need, and not the entire set.

Throughout my career as a developer I have had the occasion to use the Factory Method Pattern when appropriate, and grown to rely on it extensively in recent months as several projects have dictated. I find this pattern to be extremely useful in creating a loosely-coupled application architecture, which (as we’ve all been indoctrinated) is the cornerstone of well designed apps. It is my hope that this introduction will illuminate this pattern for the uninitiated. Even if you don’t find an immediate application for the Factory Pattern, just understanding the ‘why’ and ‘how’ of this design can be important in grasping the importance of the “open-closed” principle, and will help you to write better code. 

Let me start off by giving the standard text-book definition of the pattern:

The Factory Pattern “…define[s] an interface for creating an object, but allows the subclasses decide which class to instantiate. The Factory method lets a class defer instantiation to subclasses.” 

Chances are that many readers out there will be quite familiar this manner of verbiage. However if you need a quick primer, this more or less states that this pattern can be used when you have the need to create objects of a varying types, and whose types cannot be known before runtime. One quick aside, I’m going to call these objects ‘products’ as real life factories generally produce things called products, and it is always useful when dealing with abstractions to think in more concrete terms. The situation I’ve just described is common if the product you need to create depends on configuration settings, or more likely, responses to user interaction. 

Let’s step through a likely code example together to light a proverbial fire under this otherwise sterile illustration. I’ve chosen a product that I’m currently pretty enthused about… guitars. Now everybody knows that there are about int.MAX_VALUE types of guitars in the world, and any guitar player will tell you that you can never have too many of the darn things around. So it wouldn’t be a stretch to envision an app that queries a customer for his/her desired guitar characteristics, makes up a request for said guitar, and sends it off to a guitar factory object to do the construction of the desired guitar object, right? A superlative example if I do say so. 

For the sake of simplicity, we’re going to limit the types of guitars available to the user to ‘electric’, ‘acoustic steel-string’, and  ’acoustic nylon-string’, each of these types having unique properties, and the inherent need to be constructed in different ways. They are all guitars, however, and thus share certain properties common to all guitars. We can logically represent this commonality by defining an interface called IGuitar. IGuitar might look similar to the following:

public interface IGuitar{
function lookPretty():void;
function soundIncredible():AwestruckListener;
}

These are all of the things that our guitars need to be able to do, else we call them canoe paddles, or bits of kindling, or perhaps worse. Each guitar class that implements this interface is responsible for providing the necessary details about how it does ‘lookPretty’ and ‘soundIncredible.’ Now, you might ask how we are going to build all of these different types of guitar in one factory. The key to this trick is all in the implementation of the IGuitar Interface. Here is our GuitarFactory code:

public class GuitarFactory {
    public static function buildGuitar(guitarType:String):IGuitar {
     switch(guitarType) {
            case ‘electric’:
                return new ElectricGuitar();
                break;
            case ‘acoustic steel_string’:
                return new AcousticSteelStringGuitar();
                break;
            case ‘acoustic nylon_string’:
                return new AcousticNylonStringGuitar();
                 break;
                  default:
                        trace(guitarType + ‘ ain’t no guitar I’ve ever heard of.’);
              }
        }
}

You’ll notice that the buildGuitar method returns an instance of IGuitar, which gives us the flexibility to return any type of object that has implemented that interface. This is crucial if we intend to add more and varied types of guitars to our custom guitar shop application. For instance, we could easily add bass-guitars, balalaikas, cavaqhinhos, or any other instrument that has agreed to meet the requirements set forth in the interface. 

This example is perhaps a bit pedestrian, if not corny, but you get the idea. The main point to take away from this is the idea that you can defer creation of a given type of object until it becomes necessary to build it. This gives you a great deal of flexibility in your application, and can be extremely handy in a host of situations. Check it out for yourself.

• Will you use this class exactly the same way?
• Will you only ever need only one instance of this class?

If you answer yes to these two questions, you might have the case to build a singleton. – So here is how you go about doing it in AS3 -it’s a bit tricksy ’cause as3 has no private constructors:

Example Singleton

package somepackage{
public class MySingleton{
private static var _instance:MySingleton;
public function MySingleton(enforcer:Enforcer){}
public static function getInstance():mySingleton{
if(MySingleton._instance==null){
MySingleton._instance = new MySingleton(new Enforcer)}
return MySingleton._instance
}
public function someExampleService():void{}
}
}
class Enforcer{}

So that’s the basic code structure. Some items of note is the inclusion of the empty Enforcer class outside of the package. This is critical, as you don’t want to place your Enforcer in the package or class definition of the singleton. So lets talk about how this thing works. The key is the conditional static function getInstance. It only creates the internal variable _instance if one does not already exist. In addition to this restriction, the Enforcer class will generate an error if you try to instantiate  an instance of MySingleton using the new keyword. Try it…

Great…So how do you instantiate this pattern? Simple… just access the class methods through the getInstance() method:

MySingleton.getInstance().someExampleService()

Happy Coding!