What is source control and how to get started

In the big IT shops source control is rather common place. However in smaller shops or for individual developers a version control system may not be a top priority. A source control system may seem overly complicated and unnecessary. Fortunately they’re not as cumbersome as you might think and the benefits are well worth the small effort. 

So what exactly do we mean when we talk about source control, or version control systems? Basically a source control system provides a central place to store your code and a mechanism to track revisions of that code.

 

Source Control

One common reason people start using a source control system is when more than one developer needs to access the code. There used to be a time when our live production system served as the central repository for accessing code. Jim had a task to update a webpage so, he would connect directly to the server and make a change to the file in the live environment. Bob may have a change to make and then go do the same thing. What about quality, what if there was a mistake or a file was accidentally deleted. To avoid this Developers may keep code in another location other than the live site. For individual developers this is typically on their computer. For multiple developers, this central spot may be a shared network drive. With that risk averted what else could go wrong?

What if Jim had a lot of changes to implement. Some core functionality needed to be changed and it couldn’t be done at one time. Typically Jim would grab a copy and keep it locally until it was finished then post it. Here’s the rub, after Jim takes the copy but before he puts it back, Bob goes on the server and makes a change. Later Jim posts his changes and overwrites Bob’s code. Geez thanks Jim.

Here’s where we start to see features of a source control system come in. In this case if they were using source control, when Jim tries to put his changes in, the system would alert him that other changes had been made since he pulled his copy.

Source Versioning

So what about this versioning concept, why do I care? Have you ever used undo on your computer? You know you make a mistake, hit ctrl+z and revert back to what you had before? Here’s a question, how do you revert back to something you had yesterday or last week. If you had something versioning your files you could do just that.

Say you’re doing a website and are making some wording updates to a promotion. You post the changes and a few weeks later your client tells you there’s a law suit over that change. Apparently a customer claimed the original promotion said one thing but the company say it was something else. How do you go back and see what really was on the site? Version control.

Another scenario, you have a functional application that your client is using in production. Now you have another customer who wants to use it too. You decide to update the application to accommodate more than one client. After a few weeks of tinkering you still can’t get things the way you want. It’s functional and in your central repository but not quite right. Your client comes back and wants a change to the app in production tomorrow. Your repository copy has the new changes in it, if you make the change now it will have your unfinished changes in it. With a version control system you can pull a snapshot of the code from before you started your changes and update it without affecting your in progress changes.

 

Getting started using a source version control system

There are a variety of free and fee based solutions. Some of the big names like ClearCase and Preforce sometimes show up in the big companies but the free solutions like CVS and SVN are more popular. CVS has been around for ages and had a huge following. SVN, also known as Subversion, started as an effort to fix some of the challenges that were in CVS. These days SVN is very widely used and is pretty much the standard.

Lets take a look at SVN. Most systems have a server component and a client component. The server piece is where your code is stored and the client is an interface for you to access that code. SVN is no different. You can go out and grab the server components then go get a client too. You don’t need to do this at this point though. For this example and for simple setups, the Subversion client TortoiseSVN has everything you need. So go ahead, down load and install it.

Once installed create a directory to act as your central repository. In this case I’ll create one at c:\repo. Navigate into that directory and right click. In the context menu choose TortoiseSVN -> Create repository here. Just like that you have a functional source control system.

Lets start using our new system. Before we do I need to clarify one thing. We just created a setup that mimics a server configuration. While this example is setup locally, it could ba on a server somewhere. The next step explains how you access that content and keep a useable copy locally.

We’re ready now to use our SVN instance. Find a place on your computer where you’ll be doing your work, maybe c:\workspace. Navigate into that directory and right click. In the context menu choose SVN Chekout. This will pop up a window asking you where your repository is and how you want to get the contents. 

For the URL type in file:/// followed by the path to where you create the SVN repository earlier. This is not the working directory, rather the location of the repository. Since we installed this locally it will be something like file:///C:/repo but if this were on a server it could be http://someserver.com/repo

In this scenario we’re starting with the repository and pull the contents into our workspace. If you already had files in a workspace you could start there and push them into the repository with the import option on the context menu.

Using Your New Source Control System

Now that we have things setup lets try it out. Create a text file in your workspace called MyFile.txt. Add some content in it. Save and close. Depending on your version and setup the icon may differ but you’ll see a marker on your file like a question mark. This is telling you that this file is not in the repository or under source control. Since it is a new file we need to get it in there. Right click on a white space and choose

svn commit. The following popup will show you all files   that have been updated locally and are not in sync with the repository. you should notice that our file is listed, but is not checked. Since this is a new file we need to select it and have the SVN client add it to our repository. Make sure our file is checked and hit ok.  The confirmation screen will show that everything has been added and updated.

Now go back and make a change to that file again, Save it and take a look at the new icon. 

This exclamation point tells us that this file, which is under version control, is out of sync with the repository. Again right click and commit changes.

Now all is good and we get a Green checkmark.

So there you have it. The barebones basics of getting going with a source control system.

 

 

In future posts we’ll be using source control systems in our examples which will give you more context how this fits into a development process. Even with this basic setup you’ll be able to point your IDE to this local repository and follow along. Don’t just use it for our examples though, you can keep versions of any file this way. Version your wedding list, or Photoshop files. Whatever it is, revision control systems provide a lot of value.

For now happy versioning. 

How to fix problems with combined Flex / J2EE projects and BlazeDS

Flex Builder and Flash Builder both have the ability to setup a few aspects of your BlazeDS project for you. In a previous posting I explained how to set up a BlazeDS project in Flash Builder. When you select “Use remote object access service” you’re telling the IDE to set up a few things for you. Selecting this keeps you from having to import the BlazeDS libraries, add configuration files and set a compiler option that points to the config files.

It sounds nice, but it may not be the best solution. Flash Builder seems to be a bit buggy when you choose this option. As of this posting it seems to incorrectly set the web context for the destination call when making the actual AMF call. More specifically it seems to use the “WebContent” value instead of “WebContext”. The result is that the calls are made to http://localhost:8080/WebContent/messagebroker/amf instead of http://localhost:8080/MyProject/messagebroker/amf. While this may be a bug in the beta version of Flash Builder there are other reasons not to trust this to your IDE.

When you set this up automatically, the config files are put into your WEB-INF/flex directory for you. When you edit these files, Flash Builder prompts you asking you if you really want to do this since they are generated files. Typically you would just hit yes and update the files. Here’s the rub. If you go under the project properties and change the server configuration the IDE may delete those files from the directory. In FlashBuilder if you remove the BlazeDS support after a project has been set up it removes the config files. Why would you do this if you were writing a BlazeDS app? Well maybe someone (me) was trying to fix the destination issue I previously mentioned by changing the WebContext setting. This setting happens to be locked down in an automated setup.

Finally when your application gets all growed up and wants to move out, you’ll probably want to move the build process to a command line utility. At this point you’ll have to know about the libraries, config files and compiler options anyway. So why wait, just set it up on your own to begin with.   FlashBuilder isn’t really doing that much anyway.

 

Set it up yourself

So where to begin. Lets talk briefly about the three main styles of setup that you’ll come across online. First is what we already mentioned, having Flash Builder setup things for you in a combined Flex J2EE project. The second way many sites discuss is creating a project for flex and pointing it to an existing server that’s running BlazeDS.  This is a more prevalent option and highlights the separation of concerns that actually exists in any final solution. The third method is to manually create a combined Flex J2EE project. This third option is more ideal for smaller projects.

 

Lets look at setting up Flash Builder with BlazeDS manually. Go ahead and create a new flash project. Select J2EE for server technology, but DON’T select use remote object access. I have WTP installed so I have Flash Builder create my web app for me by selecting Create combined J2EE/Flex project using WTP.

Finish the set up as usual. Now you’ll need that BlazeDS war everyone talks about. If you don’t have it yet go get it from the Adobe Release Builds page. You can just grab the Binary Distribution. The Turnkey version just includes a lot of stuff we don’t need right now.

Once you get the War we’ll need to import it into our project. Go to File –> Import then select Archive file under General. Locate the directory where you put the blazeds.war and switch the file type to *.* then select the war.

 

Now we don’t need everything in this war, sure you can import it all but lets keep things clean.

Deselect the META-INF, classes and src directories. Also you’ll need to change the import into folder field from <project> to <project>/WebContent.

Hit Finish and say yes to overwriting web.xml. See that wasn’t so bad and you just did most of what FlashBuilder did, simply by importing that war yourself.

 

There is one other thing we need to do before we’re done. The web.xml tells Java where to find the configuration files but we need to let flex know also. It’s pretty easy, just follow my lead.

Open up the project properties and head to flex compiler. See that field additional compiler arguments?  We’re going to update it.

We want to add a compiler option pointing to the configuration files. You can use either a path that’s in the classpath  or a physical location on your drive. We’ll use the latter. Update the Additional compiler arguments to include the following –services “C:\dev\MyProject\WebContent\WEB-INF\flex\services-config.xml” where dev is your workspace directory and MyProject is your project name. 

Hit OK  and you’re done.

 

 

Setting this up manually is a good practice and will make things easier later when we migrate to Maven and Ant. Stay Tuned!!!!

Connecting Flex to Java with BlazeDS

BlazeDS offers a great mechanism to attach your flex application to backend services. In this brief overview we’ll configure flex to call a Java Class and return results. This overview assumes you’ve already setup your IDE with a basic Flex / BlazeDS project.

Main points we’ll cover

• Build the Java Class
• Expose the Class with Blaze on the server
• Configure Flex to find the Blaze service
• Build the Flex components to make the call

Build the Java Class

In your IDE switch to the Java view and create a new Java class. We’ll call it HelloFlex. Create a private variable called message. Set an initial value for this variable in the constructor. Finally create a getter method that returns the message string.

package com.grant;

public class HelloFlex {
private String message;
public HelloFlex(){
message=”HI Flex. this is Java. How are you?”;
}
public String getMessage(){
return message;
}
}

 

Expose the class with BlazeDS on the server

Under your web-inf directory you’ll fine a subdirectory called flex. Within there you’ll see the main config files blaze uses to set up the services. services-config.xml is the main file and has statements to include the others. For this example we’re creating a simple remoting service, so go ahead and open up the  remoting-config.xml. Here’s where we’ll set up the configuration for our reomting service.

Blaze calls exposed services destinations. In this remoting-config.xml we’ll set up a destination that points to our HelloFlex class.

Under the default-channels create a new destination as follows.

<?xml version=”1.0″ encoding=”UTF-8″?>
<service id=”remoting-service”
class=”flex.messaging.services.RemotingService”>

<adapters>
<adapter-definition id=”java-object” class=”flex.messaging.services.remoting.adapters.JavaAdapter” default=”true”/>
</adapters>

<default-channels>
<channel ref=”my-amf”/>
</default-channels>

<destination id=”helloflex”>
<properties>
<source>com.grant.HelloFlex</source>
</properties>
<adapter ref=”java-object” />
<channels>
<channel ref=”my-amf” />
</channels>
</destination>
</service>

 

Configure Flex to find the BlazeDS Service

Depending how you set up your workspace that set may already be done for you. In order for flex to know what channels and destinations are available, our application needs to know where these config files are. In Java, these files are in the class path and are included in the build process. In Flex we need to explicitly tell the compiler where these files are.

Right click on the project and choose properties. Under flex compiler you’ll see a textbox for additional compiler arguments. To configure the file location you’ll need an argument here called services which points to the location of your xml files.

You have two options now.

1) If the folder is part of your flex build path you can make a relative reference to the file using the –services=<file> format as follows. Notice the web-inf directory is not included in the definition. In this the folder containing the flex subfolder is on my build path.

2) If the folder is NOT on your build path you can point to the file location. This is the default method that FlashBuilder implements. We’ll use it for this example, however I suggest you move to a relative location style as soon as you can.

For an explicit file system location the flex option is slightly different. Here we use the –services “<file Location>” format. On my drive the option reads –services “C:\FlashBuilder\dev\MyProject\WebContent\WEB-INF\flex\services-config.xml”

 

Build the Flex components to make the call

Now we can get back to our flex components and make the actual call. First flip back over to your Flex Perspective and open your main mxml file.

First we’ll define the service:

<mx:RemoteObject id=”myService”  destination=”helloflex” />

The id is the name you’ll reference this service elswhere in your flex app. The destination of helloflex needs to match the destination name you entered in your remoting-config.xml

Next we’ll move to some visual components. First lets add a panel to hold our controls.

<s:Panel width=”100%” height=”100%”>
<s:layout>
<s:VerticalLayout/>
</s:layout>

</s:Panel>

And add a text box to display some results

<s:Panel width=”100%” height=”100%”>
<s:layout>
<s:VerticalLayout/>
</s:layout>

<mx:TextArea id=”result_text”/>

</s:Panel>

Now we’ll add a button on the page to use the service

<s:Panel width=”100%” height=”100%”>
<s:layout>
<s:VerticalLayout/>
</s:layout>

<mx:TextArea id=”result_text”/>
<mx:Button label=”Call Java” click=”myService.getOperation(‘getMessage’).send();”/>

</s:Panel>

This is a direct use of the RemoteObject myService. This is not a best practice. Typically you would have a function managing your calls and the button would utilize that function. For simplicity sake I’ve included the direct call for this demonstration. In this example you’ll notice we use the getOperation function and pass in the java method name we want to call.

If you were to run this now you would see no results. We have yet to define what happens when the service gets called. Lets do that now.

Create a script block to hold our action script and add a simple method that puts the response of our service in our textbox.

<fx:Script>
<![CDATA[
import mx.rpc.events.ResultEvent;
import mx.rpc.events.FaultEvent;
private function resultHandler(evt:ResultEvent):void
{
result_text.text = evt.message.body.toString();
}
]]>
</fx:Script>

To use this function we’ll go back to the service and add a handler to manage all responses.

<fx:Declarations>
<!– Place non-visual elements (e.g., services, value objects) here –>
<!– DEFINE REMOTE SERVICES WE’LL USE –>
<mx:RemoteObject
id=”myService”
destination=”helloflex”
result=”resultHandler(event)” />
</fx:Declarations>

 

Your completed code should look like this

 

<?xml version=”1.0″ encoding=”utf-8″?>
<s:Application xmlns:fx=”http://ns.adobe.com/mxml/2009″
xmlns:s=”library://ns.adobe.com/flex/spark”
xmlns:mx=”library://ns.adobe.com/flex/halo” minWidth=”1024″ minHeight=”768″>
<fx:Declarations>
<!– Place non-visual elements (e.g., services, value objects) here –>
<!– DEFINE REMOTE SERVICES WE’LL USE –>
<mx:RemoteObject
id=”myService”
destination=”helloflex”
result=”resultHandler(event)” />
</fx:Declarations>
<fx:Script>
<![CDATA[
import mx.rpc.events.ResultEvent;
import mx.rpc.events.FaultEvent;
private function resultHandler(evt:ResultEvent):void
{
result_text.text = evt.message.body.toString();
}
]]>
</fx:Script>
<s:Panel width=”100%” height=”100%”>
<s:layout>
<s:VerticalLayout/>
</s:layout>
<mx:TextArea id=”result_text”/>
<mx:Button label=”Call Java” click=”myService.getOperation(‘getMessage’).send();”/>
</s:Panel>

</s:Application>

 

That’s it! Run the application and pat yourself on the back. Congratulations! Your first end to end Flex-Java app.

 

Setting up Flex BlazeDS in FlashBuilder

One of the most compelling aspects of Flex is its ability to integrate with a wide variety of data sources. Many of the introductory tutorials online teach how to connect to http services to pull data. The result is typically an XML response. Flex makes it easy to manage XML but there are better ways. using XML requires an object on the server to be serialized to a text format which adds processing time. The response is also larger due to the variety of XML tags that need to be added in order to properly represent the object’s structure. Yes I hear you in the back telling me that JSON is a lighter weight response that doesn’t require all the tags. Regardless the response still needs to be parse out in the client. Finally the contract between client and server is not well defined with straight XML or JSON. Web services do provide a strict contract for the interface that the client can rely on but  the objects are still serialized with extraneous tags used to define the structure.

BlazeDS utilizes AMF to provide direct links between client and server objects. AMF provides access to objects through a binary protocol and eliminates the need to add additional tags that identify the object structure. It also reduces the work in flex to get the data back into a usable flex object.

Lets start working through an example by getting our workspace setup.

 

Initial Setup

Flex and Java both need to know about BlazeDS and where to look for the libraries and configuration files. FlashBuilder lends a hand with this by automating some of the process.

First things first, you’ll need to have FlashBuilder installed. The beta version can be downloaded at http://labs.adobe.com/technologies/flashbuilder4/.  Also check to make sure you have the WTP extensions installed in eclipse so you can automate creating the web application structure.

Finally for this IDE example we’re going to download the BlazeDS war from adobe at: http://opensource.adobe.com/wiki/display/blazeds/Release+Builds Just download the binary version, we don’t need the full turnkey for this. Once you have it downloaded, extract it to your drive, you should see the blazeds.war when you’re done.

In FlashBuilder create a new Flash project. Select J2EE Application server type. Select Remote object access with BlazeDS and the type. Select create combined Java/Flex using WTP. Click next.

 

On the next page, for the BlazeDS WAR file, point to the location where you extracted the files from Adobe. The system will pull all the jar files and configs from this war and add them to your project. Click finish.

You’ll notice that FlashBuilder loaded all the Jars and Config files as well as setting up the web.xml.

The web.xml tells java where to find the config files that BlazeDS needs. Remembering that Flex and Java are compiled separately and both need to know where configuration files are, lets find out where the IDE tells Flex about the config files.

Looking under the project properties under flex compiler you’ll see a compiler option is added for services.

NOTE: Without this compiler option Flex would not be able to find the BlazeDS services. When setting up blazeDS manually this flag will needed to be added by hand.

Java vs Flex: In Java the config files are loaded at run time. To change a value in the property file you simply need to restart the server to make it take effect. In Flex however this is a compile time include which means any changes to the files will need to be rebuilt into the application. Just a little note that may save you some headaches later.

 

That’s is for the setup.

Next time we’ll look at the code needed to use BlazeDS.  Stay tuned.