Apache Flex BlazeDS
==================

    Apache Flex SDK is an application development framework for easily building
    Flash-based applications for mobile devices, web browsers, and desktops.

    Apache Flex BlazeDS is the server-based Java remoting and web messaging 
    technology that enables developers to easily connect to back-end distributed 
    data and push data in real-time to Adobe® Flex® and Adobe AIR™ applications 
    for more responsive rich Internet application (RIA) experiences..

    Apache Flex BlazeDS 4.7 is the initial release of BlazeDS from the Apache
    Software Foundation.  Prior to this, releases were provided by Adobe
    Systems Inc.  This version adds new features and implements bug fixes 
    that were unavailable in previous versions.  It is compatible with most code 
    written to target Adobe Flex 4.6.

    For detailed information about Apache Flex please visit
    http://flex.apache.org/

    Apache Flex BlazeDS is a large project with many pieces.  The software is
    implemented partially in ActionScript and partially in Java.

    Currently supported platforms include:

        Microsoft Windows
        Mac OS X
        Apple iOS
        Google Android
        RIM BlackBerry
        Linux

    Apache Flex is the software evolution of the popular Adobe BlazeDS project.

    The community surrounding Flex is vast, diverse, distributed globally, and
    with all levels of proficiency in software development.

    There has been more that 30,000 installs of Apache Flex. The Apache Flex web
    site gets 3 quarters of a million page views a year and more than 250,000
    unique visitors a year.


Getting the convenience packages for Apache Flex
================================================

    TBD

Getting the latest sources via git
==================================

    Getting the source code is the recommended way to get Apache Flex BlazeDS.

    You can always checkout the latest source via git using the following
    command:

	 git clone https://git-wip-us.apache.org/repos/asf/flex-blazeds.git blazeds
	 cd blazeds
	 git checkout develop

    Apache Flex BlazeDS also requires source code from other Apache Flex git
    repositories.  To get the latest source via git for the Apache Flex SDK
    use the following command:

	 git clone https://git-wip-us.apache.org/repos/asf/flex-sdk.git sdk
	 cd sdk
	 git checkout develop

    Linux support is currently experimental and you may run into issues. Apache
    Flex would like to see a fully supported Linux release, but we need support
    from the community in order to do that. Please help out if you can.

    For further information visit http://flex.apache.org/download-source.html

Building Apache Flex BlazeDS 4.7
================================

    Apache Flex BlazeDS is a large project. It requires some build tools which must be
    installed prior to building BlazeDS and it depends on some external software
    which are downloaded as part of the build process.  Some of these have
    different licenses.  See the Software Dependencies section for more
    information on the external software dependencies.

    From Apache's perspective, the Adobe Flash Player and Adobe AIR have
    excluded licenses so they can not be bundled with the Apache Flex binaries.
    They must be installed prior to building Apache Flex.

    Linux support is currently experimental and while it is possible to compile
    BlazeDS it has not been fully tested so you may run into issues.

Install Prerequisites
---------------------

    Before building BlazeDS you must install the following software and set the
    corresponding environment variables using absolute file paths.  Relative
    file paths will result in build errors.

    The environment variables PLAYERGLOBAL_HOME, AIR_HOME, FLASHPLAYER_DEBUGGER,
    FLEX_HOME can also be set in the property file
    called env.properties. See the env-template.properties file for
    instructions.

    The Adobe Flash Player playerglobal.swc is needed to compile all the
    ActionScript components.  The Adobe Flash Player
    content debugger is used by checkintests and other pieces of the test
    subsystem to run compiled applications.

    ==================================================================================
    SOFTWARE                                    ENVIRONMENT VARIABLE (absolute paths)
    ==================================================================================

    Java SDK 1.6 or greater (*1)                JAVA_HOME
        (for Java 1.7 see note at (*2))

    Ant 1.7.1 or greater (*1)                   ANT_HOME
        (for Java 1.7 see note at (*2))

    Adobe AIR Integration Kit (*3)              AIR_HOME

    Adobe Flash Player Content Debugger (*4)    FLASHPLAYER_DEBUGGER

    Adobe Flash Player playerglobal swcs (*5)   PLAYERGLOBAL_HOME

    Apache Flex SDK (*6)                        FLEX_HOME

    ==================================================================================

    *1) The bin directories for ANT_HOME and JAVA_HOME should be added to your
        PATH.

        On Windows, set PATH to

            PATH=%PATH%;%ANT_HOME%\bin;%JAVA_HOME%\bin

        On the Mac (bash), set PATH to

            export PATH="$PATH:$ANT_HOME/bin:$JAVA_HOME/bin"

         On Linux make sure you path include ANT_HOME and JAVA_HOME.

    *2)  If you are using Java SDK 1.7 or greater on a Mac you must use Ant 1.8
         or greater. If you use Java 1.7 with Ant 1.7, ant reports the java
         version as 1.6 so the JVM args for the data model (-d32/-d64) will not
         be set correctly and you will get compile errors.

    *3) The Adobe AIR integration kit for Windows can be downloaded from:
           http://airdownload.adobe.com/air/win/download/13.0/AdobeAIRSDK.zip

         The Adobe AIR integration kit for Mac can be downloaded from:
            http://airdownload.adobe.com/air/mac/download/13.0/AdobeAIRSDK.tbz2

          The Adobe AIR integration kit for Linux can be downloaded from:
            http://airdownload.adobe.com/air/lin/download/2.6/AdobeAIRSDK.tbz2

        This version of Apache Flex was certified for use with AIR 13.0, and
        should be compatible with other versions of AIR newer than 3.1. However
        it hasn't been fully tested on AIR 3.2, 3.3, 3.5, 3.6 or 3.7.

        Download the AIR SDK for your platform and unzip it. Set AIR_HOME to the
        absolute path of the AIR SDK directory.

    *4) The Adobe Flash Player content debuggers can be found here:
            http://www.adobe.com/support/flashplayer/downloads.html

        This version of Apache Flex was certified for use with Adobe Flash
        Player 11.1, and is compatible with versions 10.2 through 13.0. It has
        been tested with versions 11.1, 11.7, 11.8, 11.9 and 12.0 on Windows
        and Mac. It has been compiled against other Adobe Flash Player versions
        but has not been fully tested. It has not been fully tested on Linux.

        On Windows, set FLASHPLAYER_DEBUGGER to the absolute path including the
        filename of the FlashPlayerDebugger.exe. Note the filename of flash
        player debugger maybe different.
           e.g. C:\MyPath\FlashPlayerDebugger.exe

        On the Mac, set FLASHPLAYER_DEBUGGER to the absolute path of
        Flash Player Debugger.app/Contents/MacOS/Flash Player Debugger

        On Linux, set FLASHPLAYER_DEBUGGER to the absolute path of
        flashplayerdebugger

    *5) The Adobe Flash Player playerglobal.swc for 11.1 can be downloaded from:
            http://download.macromedia.com/get/flashplayer/updaters/11/playerglobal11_1.swc

        Use URL above to download playerglobal11_1.swc. Create the directory,
        player/11.1 and copy playerglobal11_1.swc to
        player/11.1/playerglobal.swc.

        Set PLAYERGLOBAL_HOME to the absolute path of the player directory (not
        including the version subdirectory). The target-player option controls
        which PLAYERGLOBAL_HOME subdirectory is used.

        Other more recent versions of Adobe Flash Player playerglobal.swc can be
        downloaded from:
            http://download.macromedia.com/get/flashplayer/updaters/11/playerglobal11_2.swc
            http://download.macromedia.com/get/flashplayer/updaters/11/playerglobal11_3.swc
            http://download.macromedia.com/get/flashplayer/updaters/11/playerglobal11_4.swc
            http://download.macromedia.com/get/flashplayer/updaters/11/playerglobal11_5.swc
            http://download.macromedia.com/get/flashplayer/updaters/11/playerglobal11_6.swc
            http://download.macromedia.com/get/flashplayer/updaters/11/playerglobal11_7.swc
            http://download.macromedia.com/get/flashplayer/updaters/11/playerglobal11_8.swc
            http://download.macromedia.com/get/flashplayer/updaters/11/playerglobal11_9.swc
            http://download.macromedia.com/get/flashplayer/updaters/12/playerglobal12_0.swc
            http://download.macromedia.com/get/flashplayer/updaters/13/playerglobal13_0.swc

        These can be used with Apache Flex but not all have not been fully
        tested.

    *6) The Apache Flex SDK is required to build some of the ActionScript code.

        Set FLEX_HOME to the absolute path of Apache Flex SDK.

FlashPlayer Configuration
-------------------------

    For testing, the Adobe Flash Player's mm.cfg file must have the following
    entries

        ErrorReportingEnable=1
        TraceOutputFileEnable=1

    and a FlashPlayerTrust file must allow local SWFs to access local files.


Adobe Flash Player Version Support
----------------------------------

    Apache Flex BlazeDS defaults to using the Adobe Flash Player 11.1. The SDK
    can be used with Flash Player versions 10.2, 10.3, 11.0, 11.1, 11.2, 11.3,
    11.4, 11.5, 11.6, 11.7, 11.8, 11.9, 12.0 and 13.0.

    It is recommended that you update to the latest version of Adobe Flash
    Player.  Newer versions of the Adobe Flash player address security
    vulnerabilities, fix bugs/issues, increase stability, and implement new
    features.

    To use the SDK for another version of the Adobe Flash Player either:

    Change the flex-config.xml configuration file to specify another version of
    the Adobe Flash Player.

    OR

    Change the playerglobal.version in the build.properties file to have a value
    other than "11.1". For this change to take effect the SDK needs to be
    recompiled.  For example to compile against the latest version of the Adobe
    Flash Player set the value of playerglobal.version to be "12.0" like so:

        playerglobal.version = 13.0

    OR

    Compile the SDK with a -Dplayerglobal.version=<version> option, where
    <version> is the Adobe Flash Player version to compile the SDK against.


    Different versions of the Adobe Flash Player require different versions of
    playerglobal.swc.

    These can be found at:

    http://download.macromedia.com/get/flashplayer/installers/archive/playerglobal/playerglobal10_2.swc
    http://download.macromedia.com/get/flashplayer/installers/archive/playerglobal/playerglobal10_3.swc
    http://download.macromedia.com/get/flashplayer/updaters/11/playerglobal11_0.swc
    http://download.macromedia.com/get/flashplayer/updaters/11/playerglobal11_1.swc
    http://download.macromedia.com/get/flashplayer/updaters/11/playerglobal11_2.swc
    http://download.macromedia.com/get/flashplayer/updaters/11/playerglobal11_3.swc
    http://download.macromedia.com/get/flashplayer/updaters/11/playerglobal11_4.swc
    http://download.macromedia.com/get/flashplayer/updaters/11/playerglobal11_5.swc
    http://download.macromedia.com/get/flashplayer/updaters/11/playerglobal11_6.swc
    http://download.macromedia.com/get/flashplayer/updaters/11/playerglobal11_7.swc
    http://download.macromedia.com/get/flashplayer/updaters/11/playerglobal11_8.swc
    http://download.macromedia.com/get/flashplayer/updaters/11/playerglobal11_9.swc
    http://download.macromedia.com/get/flashplayer/updaters/12/playerglobal12_0.swc
    http://download.macromedia.com/get/flashplayer/updaters/13/playerglobal13_0.swc

    Copy the target playerglobal.swc to the directory:

        frameworks/libs/player/<version>/playerglobal.swc

    Where <version> is the major and minor version numbers of the Adobe Flash
    Player separated by a period or full stop.

    If all of the playerglobal swcs where installed the frameworks/libs/player
    directory structure would look like this.

        /frameworks
            /libs
                /player
                    /10.2
                         /playerglobal.swc
                    /10.3
                         /playerglobal.swc
                    /11.0
                         /playerglobal.swc
                    /11.2
                         /playerglobal.swc
                    /11.2
                         /playerglobal.swc
                    /11.3
                         /playerglobal.swc
                    /11.4
                         /playerglobal.swc
                    /11.5
                         /playerglobal.swc
                    /11.6
                         /playerglobal.swc
                    /11.7
                         /playerglobal.swc
                    /11.8
                         /playerglobal.swc
                    /11.9
                         /playerglobal.swc
                    /12.0
                         /playerglobal.swc
                    /13.0
                         /playerglobal.swc

    Apache Flex has been tested with Adobe Flash Player 11.1, 11.5, 11.7, 11.8,
    11.9, 12.0 nd 13.0 on Windows and Mac.

    Apache Flex has not been tested on Linux so some issue may exist in this
    release.

    It compiles against other Adobe Flash Player versions and is expected to
    work but their may be some issues, particularly with the earlier 10.2 and
    10.3 versions of the Adobe Flash Player.

Software Dependencies
---------------------

    Apache Flex uses third-party code that will be downloaded as part of the
    Apache Flex build.  In addition, there is some optional third-party code
    that you can choose to download if you would like to take advantage of the
    features offered and you agree to the license terms.

    The Apache Version 2.0 license is in the LICENSE file.

    The following dependencies have licenses which are, or are compatible with,
    the Apache Version 2.0 license.  You will not be prompted to acknowledge the
    download.  Most of the jars are installed in lib/external.

        activemq - http://archive.apache.org/dist/activemq/apache-activemq/5.3.1/apache-activemq-5.3.1-bin.zip
        codec - http://archive.apache.org/dist/commons/codec/binaries/commons-codec-1.5-bin.zip
        commons-collections - http://archive.apache.org/dist/commons/collections/binaries/commons-collections-3.1.tar.gz
        commons-fileupload - http://archive.apache.org/dist/commons/fileupload/binaries/commons-fileupload-1.1.zip
        commons-httpclient - http://archive.apache.org/dist/httpcomponents/commons-httpclient/binary/commons-httpclient-3.1.zip
        commons-logging - http://archive.apache.org/dist/commons/logging/binaries/commons-logging-1.1.1-bin.zip
        hsqldb - http://downloads.sourceforge.net/project/hsqldb/hsqldb/hsqldb_1_8_0/hsqldb_1_8_0_10.zip?r=http%3A%2F%2Fsourceforge.net%2Fprojects%2Fhsqldb%2Ffiles%2Fhsqldb%2Fhsqldb_1_8_0%2F&amp;ts=1378509998&amp;use_mirror=softlayer-dal
        jms - http://downloads.sourceforge.net/project/openjms/openjms/openjms-0.7.6.1/openjms-0.7.6.1.zip?r=http%3A%2F%2Fsourceforge.net%2Fprojects%2Fopenjms%2Ffiles%2Fopenjms%2Fopenjms-0.7.6.1%2F&amp;ts=1378512874&amp;use_mirror=hivelocity
        log4j - http://archive.apache.org/dist/logging/log4j/1.2.14/logging-log4j-1.2.14.zip
        spring-framework - http://s3.amazonaws.com/dist.springframework.org/release/SPR/spring-framework-3.0.3.RELEASE.zip
        spring-security - http://s3.amazonaws.com/dist.springframework.org/release/SEC/spring-security-3.0.3.RELEASE.zip
        spring-flex - http://repo1.maven.org/maven2/org/springframework/flex/spring-flex-core/1.5.2.RELEASE/spring-flex-core-1.5.2.RELEASE.jar
        jakarta-taglibs - http://archive.apache.org/dist/jakarta/taglibs/standard/binaries/jakarta-taglibs-standard-1.1.2.zip
        aopalliance - http://downloads.sourceforge.net/project/aopalliance/aopalliance/1.0/aopalliance.zip?r=http%3A%2F%2Fsourceforge.net%2Fprojects%2Faopalliance%2Ffiles%2Faopalliance%2F1.0%2F&amp;ts=1378515484&amp;use_mirror=softlayer-dal
        backport - http://downloads.sourceforge.net/project/backport-jsr166/backport-jsr166/2.2/backport-util-concurrent-2.2.zip?r=http%3A%2F%2Fsourceforge.net%2Fprojects%2Fbackport-jsr166%2Ffiles%2Fbackport-jsr166%2F2.2%2F&amp;ts=1378515970&amp;use_mirror=heanet
        cglib - http://downloads.sourceforge.net/project/cglib/cglib2/cglib%202.1_03/cglib-nodep-2.1_3.jar?r=http%3A%2F%2Fsourceforge.net%2Fprojects%2Fcglib%2Ffiles%2Fcglib2%2Fcglib%25202.1_03%2F&amp;ts=1378516297&amp;use_mirror=hivelocity
        jackson-core - http://repository.codehaus.org/org/codehaus/jackson/jackson-core-asl/1.0.0/jackson-core-asl-1.0.0.jar
        tomcat - http://archive.apache.org/dist/tomcat/tomcat-6/v6.0.29/bin/apache-tomcat-6.0.29.zip
        xalan - http://archive.apache.org/dist/xml/xalan-j/binaries/xalan-j_2_6_0-bin.tar.gz
        xerces - http://archive.apache.org/dist/xerces/j/Xerces-J-bin.2.9.1.zip
        ExcludeDoclet.java - http://sixlegs.com/misc/ExcludeDoclet.java
        mx4j - http://repo1.maven.org/maven2/mx4j/mx4j-jmx/1.1.1/mx4j-jmx-1.1.1.jar
        axis - http://archive.apache.org/dist/axis/axis/java/1.4/axis-bin-1_4.zip
        testng - http://mirrors.ibiblio.org/pub/mirrors/maven2/org/testng/testng/5.8/testng-5.8-jdk15.jar

Using the Binary Distribution
-----------------------------

    TBD

Building the Framework in a Binary Distribution
-----------------------------------------------

    The source for most of the framework is included in the binary distribution.
    It can be useful if you wish to debug and/or extend components.

    When you have all the prerequisites in place and the environment variables
    set, (see Install Prerequisites above), use

        cd <blazeds.dir>
        ant main        (or just ant since the default target is main)

    to download the third-party dependencies and build BlazeDS.  You 
    may be prompted to acknowledge some of the downloads.  Since the third-party
    dependencies take a little while to download and they don't change very
    often, they are not cleaned with the regular clean target.

    To clean the build, of everything other than the downloaded third-party
    dependencies use

        ant clean

    To clean the build, of everything, including the downloaded third-party
    dependencies use

        ant super-clean (which is just thirdparty-clean followed by clean)

Building the Source in the Source Distribution
----------------------------------------------

    When you have all the prerequisites in place and the environment variables
    set (see Install Prerequisites above), use

        cd <blazeds.dir>
        ant main        (or just ant since the default target is main)

    to download the thirdparty dependencies and build the source.  You may be
    prompted to acknowledge and/or confirm some of the downloads.  Since the
    third-party dependencies take a little while to download and they don't
    change very often, they are not cleaned with the regular clean target.

    To clean the build, of everything other than the downloaded third-party
    dependencies use

        ant clean

    To clean the build, of everything, including the downloaded third-party
    dependencies use

        ant super-clean (which is just thirdparty-clean followed by clean)

    To generate a source distribution package and a binary distribution package
    use

        ant -Dbuild.number=<YYYYMMDD> -Dbuild.noprompt= release

    The packages can be found in the "out" subdirectory.

    To build the ASDoc package

        ant asdoc-package

    To get a brief listing of all the targets type

        ant -projecthelp


Thanks for using Apache Flex BlazeDS.  Enjoy!

                                          The Apache Flex Project
                                          <http://flex.apache.org>