////////////////////////////////////////////////////////////////////////////////
//
//  Licensed to the Apache Software Foundation (ASF) under one or more
//  contributor license agreements.  See the NOTICE file distributed with
//  this work for additional information regarding copyright ownership.
//  The ASF licenses this file to You under the Apache License, Version 2.0
//  (the "License"); you may not use this file except in compliance with
//  the License.  You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
//  Unless required by applicable law or agreed to in writing, software
//  distributed under the License is distributed on an "AS IS" BASIS,
//  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
//  See the License for the specific language governing permissions and
//  limitations under the License.
//
////////////////////////////////////////////////////////////////////////////////

package mx.managers
{

import flash.display.DisplayObject;
import flash.display.LoaderInfo;
import flash.events.StatusEvent;
import flash.events.TimerEvent;
import flash.net.navigateToURL;
import flash.net.URLRequest;
import flash.utils.Dictionary;
import flash.utils.Timer;
import mx.core.FlexGlobals;
import mx.core.mx_internal;
import mx.core.Singleton;
import mx.events.BrowserChangeEvent;
import mx.managers.BrowserManager;
import mx.managers.IHistoryManagerClient;
import mx.managers.HistoryManagerGlobals;

use namespace mx_internal;

[ExcludeClass]

/**
 *  @private
 */
public class HistoryManagerImpl implements IHistoryManager
{
    include "../core/Version.as";

    //--------------------------------------------------------------------------
    //
    //  Implementation notes
    //
    //--------------------------------------------------------------------------

    /*
        HistoryManager works in conjunction with certain components
        and with an invisible "history SWF".

        The history SWF
        ---------------

        The HTML wrapper for an MXML application contains an invisible iframe
        named _history which contains history.swf.

        This SWF's sole purpose is to encode state information for the 
        MXML application in the query parameters of its URL.
        
        HistoryManager-aware components
        -------------------------------
                
        In order to support history management, a component must implement
        the IHistoryManagerClient interface and must register with HistoryManager.

        When the application state is considered to have changed, someone
        must call <code>HistoryManager.save()</code>; in response, the HistoryManager calls
        the <code>saveState()</code> method of all the registered components.

        Each registered component returns an Object containing arbitrary
        state information such as { selectedIndex: 1 }.

        HistoryManager encodes the state information for all registered
        components into the query parameters of a URL for the history SWF.
        For example, the query parameters might be
        
            ?ce41-selectedIndex=1&10f7-selectedIndex=2
        
        In order to keep the length of the URL within the browser's limits,
        the identity of the component is specified by a short hash string
        (such as "ce41" or "1047" above) computed from its toString() string.

        The <code>save()</code> method reloads the _history iframe with the new URL
        that contains the MXML apps' state info in its query parameters.

        The browser stores these various URLs, representing various states
        of the application, in its history cache.
        
        When the user clicks the browser's Back button, the browser loads
        a previous URL into the _history iframe. This causes the history.swf
        to be reloaded.
        
        When the history.swf is reloaded, it decodes its URL and calls
        HistoryManager.load(). HistoryManager then calls the loadState()
        methods of all registered components. It ensures that loadState()
        is called on shallowly nested components before being called
        on more deeply nested components, so that, for example, an Accordion
        inside a ViewStack works properly.

        Handshakes
        ----------
        
        HistoryManager is initialized when the application starts.
        
        When HistoryManager is initialized by the init() method,
        it periodically attempts to contact the history.swf
        using a LocalConnection to determine whether it has been loaded
        and has completed its own initialization.

        The "handshake" consists of the following sequence:
            HistoryManager.initHandshake()
            register() in history.swf
            HistoryManager.registered()
        
        A corresponding handshake is initiated by the initApp() method
        of the history.swf.

        It consists of the following sequence:
            initHandshake() in history.swf
            HistoryManager.registerHandshake()
            registered() in history.swf
            HistoryManager.load()

    */

    //--------------------------------------------------------------------------
    //
    //  Class constants
    //
    //--------------------------------------------------------------------------
    
    /**
     *  @private
     *  The interval between handshake attempts.
     */
    private static const HANDSHAKE_INTERVAL:int = 500; // milliseconds

    /**
     *  @private
     *  The maximum number of handshake attempts.
     */
    private static const MAX_HANDSHAKE_TRIES:int = 100;
    
    /*
     *  The following three constants are used to encode state information
     *  about multiple objects into the query parameters of an URL.
     *  The query parameters might look like this:
     *  ?8ce2-selectedIndex=1&47f0-selectedIndex=2
     */
    
    /**
     *  @private
     *  The separator between the object identifier (the crc of its path)
     *  and the property name.
     */
    private static const ID_NAME_SEPARATOR:String = "-";
    
    /**
     *  @private
     *  The separator between the property name and the property value.
     */
    private static const NAME_VALUE_SEPARATOR:String = "=";
    
    /**
     *  @private
     *  The separator between consecutive object/property/value triples.
     */
    private static const PROPERTY_SEPARATOR:String = "&";
    
    //--------------------------------------------------------------------------
    //
    //  Class variables
    //
    //--------------------------------------------------------------------------

    /**
     *  @private
     */
    private static var systemManager:ISystemManager;

    /**
     *  @private
     */
    private static var instance:IHistoryManager;

    /**
     *  @private
     *  CRC for the app.
     */
    private static var appID:String;

    /**
     *  @private
     *  URL for history frame.
     *  This is passed to the SWF via the FlashStatic Vars in the HTML wrapper,
     *  and is currently "/dev/flex-internal?action=history_html".
     */
    private static var historyURL:String;

    //--------------------------------------------------------------------------
    //
    //  Class methods
    //
    //--------------------------------------------------------------------------

    /**
     *  @private
     */
    public static function getInstance():IHistoryManager
    {
        if (!instance)
        {
            systemManager = SystemManagerGlobals.topLevelSystemManagers[0];
            instance = new HistoryManagerImpl();
        }

        return instance;
    }

    //--------------------------------------------------------------------------
    //
    //  Constructor
    //
    //--------------------------------------------------------------------------

    /**
     *  @private
     */
    public function HistoryManagerImpl()
    {
        super();

        if (instance)
            throw new Error("Instance already exists.");

        if (appID)
            return;

        if (!("historyManagementEnabled" in FlexGlobals.topLevelApplication) ||
            !FlexGlobals.topLevelApplication.historyManagementEnabled)
            return;

        var loaderInfo:LoaderInfo;
        
        // Added to support Cross-versioning issue,
        // so one needs to set the Singleton.loaderInfo object
        // to the loaderInfo of the top-most object
        if (HistoryManagerGlobals.loaderInfo)
        {
            loaderInfo = HistoryManagerGlobals.loaderInfo;
        }
        else
        {
            // Get values that were passed in via the FlashVars
            // in the HTML wrapper.
            loaderInfo = DisplayObject(systemManager).loaderInfo;
        }
            
        var appURL:String;

        // Use our URL as the unique CRC for this movie.
        if (HistoryManagerGlobals.loaderInfo) 
            appURL = HistoryManagerGlobals.loaderInfo.url;
        else 
            appURL = DisplayObject(systemManager).loaderInfo.url;


        appID = calcCRC(appURL);

        BrowserManager.getInstance().addEventListener(BrowserChangeEvent.BROWSER_URL_CHANGE, browserURLChangeHandler);
        BrowserManager.getInstance().initForHistoryManager();

    }

    //--------------------------------------------------------------------------
    //
    //  Variables
    //
    //--------------------------------------------------------------------------
        
    /**
     *  @Private
     *  An Array of objects that will save and load state information.
     *  Each object must implement the IHistoryManagerClient interface.
     *  
     *  @langversion 3.0
     *  @playerversion Flash 9
     *  @playerversion AIR 1.1
     *  @productversion Flex 3
     */
    private var registeredObjects:Array = [];
    
    /**
     *  @private
     *  A map from a registed object's path to its RegistrationInfo
     *  (path crc and path depth).
     */
    private var registrationMap:Dictionary;

    /**
     *  @private
     *  Pending states for deferred restoration.
     */
    private var pendingStates:Object = {};

    /**
     *  @private
     *  Pending query string to be sent to history.swf.
     */
    private var pendingQueryString:String;
    
    //--------------------------------------------------------------------------
    //
    //  Methods
    //
    //--------------------------------------------------------------------------

    /**
     *  Registers an object with the HistoryManager.
     *  The object must implement the IHistoryManagerClient interface.
     *
     *  @param obj Object to register.
     *
     *  @see mx.managers.IHistoryManagerClient
     *  
     *  @langversion 3.0
     *  @playerversion Flash 9
     *  @playerversion AIR 1.1
     *  @productversion Flex 3
     */ 
    public function register(obj:IHistoryManagerClient):void
    {
        if (!("historyManagementEnabled" in FlexGlobals.topLevelApplication) ||
            !FlexGlobals.topLevelApplication.historyManagementEnabled)
            return;

        // Ensure that this object isn't already registered.
        unregister(obj);
        
        // Add the object to the Array of all registered objects.
        registeredObjects.push(obj);
                
        // Get a "path" string such as "Application_1.VBox0.hb:HBox.main:
        // Panel.bodyStack:ViewStack.checkoutView:VBox.accordion:Accordion"
        // that uniquely represents this object in the visual hierarchy
        // of the application.
        var path:String = getPath(obj);
        
        // Calculate a 4-character hex CRC of this path as a short
        // identifier for the object to be encoded into the
        // query parameters of the history URL.
        var crc:String = calcCRC(path);
        
        // Determine the depth of the object in the visual hierarchy.
        // This is important because state must be restored
        var depth:int = calcDepth(path);
        
        // Store the crc and depth of the registered object in a
        // RegistrationInfo instance kept in the HistoryManager's
        // registrationMap. Given a registed object, we can look up
        // its crc and depth using getRegistrationInfo().
        if (!registrationMap)
            registrationMap = new Dictionary(true);
        registrationMap[obj] = new RegistrationInfo(crc, depth);
        
        // Sort the Array of all registered objects according to their depth.
        registeredObjects.sort(depthCompare);
        
        // See if there is a pending state for this object.
        if (pendingStates[crc])
        {
            obj.loadState(pendingStates[crc]);
            delete pendingStates[crc];
        }
    }

    /**
     *  @private
     */
    private function getPath(obj:IHistoryManagerClient):String
    {
        return obj.toString();
    }
    
    /**
     *  @private
     *  Function to calculate a cyclic rendundancy checksum (CRC).
     *  This returns a 4-character hex string representing a 16-bit uint
     *  calculated from the specified string using the CRC-CCITT mask.
     *  In http://www.joegeluso.com/software/articles/ccitt.htm,
     *  the following sample input and output is given to check
     *  this implementation:
     *  "" -> "1D0F"
     *  "A" -> "9479"
     *  "123456789" -> "E5CC"
     *  "AA...A" (256 A's) ->"E938"
     */
    private function calcCRC(s:String):String
    {
        var crc:uint = 0xFFFF;

        // Process each character in the string.
        var n:int = s.length;
        for (var i:int = 0; i < n; i++)
        {
            var charCode:uint = s.charCodeAt(i);
            
            // Unicode characters can be greater than 255.
            // If so, we let both bytes contribute to the CRC.
            // If not, we let only the low byte contribute.
            var loByte:uint = charCode & 0x00FF;
            var hiByte:uint = charCode >> 8;
            if (hiByte != 0)
                crc = updateCRC(crc, hiByte);
            crc = updateCRC(crc, loByte);
        }

        // Process 2 additional zero bytes, as specified by the CCITT algorithm.
        crc = updateCRC(crc, 0);
        crc = updateCRC(crc, 0);

        return crc.toString(16);
    }

    /**
     *  @private
     */
    private function updateCRC(crc:uint, byte:uint):uint
    {
        const poly:uint = 0x1021; // CRC-CCITT mask

        var bitMask:uint = 0x80;

        // Process each bit in the byte.
        for (var i:int = 0; i < 8; i++)
        {
            var xorFlag:Boolean = (crc & 0x8000) != 0;
            
            crc <<= 1;
            crc &= 0xFFFF;

            if ((byte & bitMask) != 0)
                crc++;

            if (xorFlag)
                crc ^= poly;

            bitMask >>= 1;
        }

        return crc;
    }

    /**
     *  @private
     */
    private function calcDepth(path:String):int
    {
        return path.split(".").length;
    }
    
    /**
     *  @private
     */
    private function depthCompare(a:Object, b:Object):int
    {
        var regInfoA:RegistrationInfo = getRegistrationInfo(IHistoryManagerClient(a));
        var regInfoB:RegistrationInfo = getRegistrationInfo(IHistoryManagerClient(b));
        
        // Guard against the possibility of an object's 
        // registration info not being found.
        if (!regInfoA || !regInfoB)
            return 0;
        
        if (regInfoA.depth > regInfoB.depth)
            return 1;
        
        if (regInfoA.depth < regInfoB.depth)
            return -1;
            
        return 0;
    }
    
    /**
     *  @private
     */
    private function getRegistrationInfo(
                                obj:IHistoryManagerClient):RegistrationInfo
    {
        return registrationMap ? registrationMap[obj] : null;
    }
    
    /**
     *  Unregisters an object with the HistoryManager.
     *
     *  @param obj Object to unregister.
     *  
     *  @langversion 3.0
     *  @playerversion Flash 9
     *  @playerversion AIR 1.1
     *  @productversion Flex 3
     */
    public function unregister(obj:IHistoryManagerClient):void
    {
        if (!("historyManagementEnabled" in FlexGlobals.topLevelApplication) ||
            !FlexGlobals.topLevelApplication.historyManagementEnabled)
            return;

        // Find the index of the object in the Array of all
        // registered objects; -1 means not found.
        var index:int = -1;
        var n:int = registeredObjects.length;
        for (var i:int = 0; i < n; i++)
        {
            if (registeredObjects[i] == obj)
            {
                index = i;
                break;
            }
        }
            
        // If the object was found in the Array, remove it.
        if (index >= 0)
            registeredObjects.splice(index, 1);
        
        // Remove it from the map as well.
        if (obj && registrationMap)
            delete registrationMap[obj];
    }

    /**
     *  Saves the application's current state so it can be restored later.
     *  This method is automatically called by navigator containers
     *  whenever their navigation state changes.
     *  If you registered an interface with the HistoryManager,
     *  you are responsible for calling the <code>save()</code> method
     *  when the application state changes.
     *  
     *  @langversion 3.0
     *  @playerversion Flash 9
     *  @playerversion AIR 1.1
     *  @productversion Flex 3
     */ 
    public function save():void
    {
        if (!("historyManagementEnabled" in FlexGlobals.topLevelApplication) ||
            !FlexGlobals.topLevelApplication.historyManagementEnabled)
            return;

        var haveState:Boolean = false;

        // Query string always starts with the application identifier.
        var queryString:String = "app=" + appID;
        
        // Call saveState() on every registered object
        // to get an Object containing its state information.
        var n:int = registeredObjects.length;
        for (var i:int = 0; i < n; i++)
        {
            var registeredObject:IHistoryManagerClient = registeredObjects[i];
            var stateInfo:Object = registeredObject.saveState();
                
            // stateInfo might be something like { selectedIndex: 1 }
            
            // Encode the stateInfo into the query string, building up
            // a string like "ce41-selectedIndex=1&10f7-selectedIndex=2"
            // that specifies objects (via the crcs of their paths),
            // property names, and property values.
            var crc:String = getRegistrationInfo(registeredObject).crc;
            for (var name:String in stateInfo)
            {
                var value:Object = stateInfo[name];
                
                if (queryString.length > 0)
                    queryString += PROPERTY_SEPARATOR;
                queryString += crc;
                queryString += ID_NAME_SEPARATOR;
                queryString += escape(name);
                queryString += NAME_VALUE_SEPARATOR;
                queryString += escape(value.toString());
                haveState = true;
            }
        }
        
        // If any registered objects specified any state information to save,
        // reload the history SWF with an URL that encodes all the state info.
        if (haveState)
        {
            pendingQueryString = queryString;
            FlexGlobals.topLevelApplication.callLater(this.submitQuery);
        }
    }
    
    /**
     *  @private
     *  Reloads the _history iframe with the history SWF.
     */
    private function submitQuery():void
    {
        if (pendingQueryString)
        {
            BrowserManager.getInstance().setFragment(pendingQueryString);
            pendingQueryString = null;
            if ("resetHistory" in FlexGlobals.topLevelApplication)
                FlexGlobals.topLevelApplication.resetHistory = true;
        }
    }
    
    //--------------------------------------------------------------------------
    //
    //  Event handlers
    //
    //--------------------------------------------------------------------------


    /**
     *  @private
     *  Loads state information.
     *  Called by the registered() method of history.swf
     *  after we have returned its handshake.
     *
     *  @param stateVars State information.
     */
    public function browserURLChangeHandler(event:BrowserChangeEvent):void
    {
        var p:String;
        var crc:String;
            
        if (!("historyManagementEnabled" in FlexGlobals.topLevelApplication) ||
            !FlexGlobals.topLevelApplication.historyManagementEnabled)
            return;

        var pieces:Array = event.url.split(PROPERTY_SEPARATOR);
        var stateVars:Object = {};
        var n:int = pieces.length;
        for (var i:int = 0; i < n; i++)
        {
            var nameValuePair:Array = pieces[i].split(NAME_VALUE_SEPARATOR);
            stateVars[nameValuePair[0]] = parseString(nameValuePair[1]);
        }

        var params:Object = {};


        // Unpack the stateVars into parameter objects for each state interface.
        // stateVars looks like
        //   { ce41-selectedIndex: 1, 10f7-selectedIndex: 2 }
        // params will look like
        //   { ce41: { selectedIndex: 1 }, 10f7: { selectedIndex: 2 } }
        for (p in stateVars)
        {
            var crclen:int = p.indexOf(ID_NAME_SEPARATOR)
            if (crclen > -1)
            {
                crc = p.substr(0, crclen);
                var name:String = p.substr(crclen + 1, p.length);
                var value:Object = stateVars[p];
                
                if (!params[crc])
                    params[crc] = {};
                
                params[crc][name] = value;
            }
        }       
        
        // Call loadState() on all registered objects.
        n = registeredObjects.length;
        for (i = 0; i < n; i++)
        {
            var registeredObject:IHistoryManagerClient = registeredObjects[i];
            crc = getRegistrationInfo(registeredObject).crc;

            registeredObject.loadState(params[crc]);
            delete params[crc];
        }
        
        // Save off any remaining state variables in the pendingStates object.
        // This way the state can be restored if the interface
        // is instantiated later.
        for (p in params)
        {
            pendingStates[p] = params[p];
        }

    }

    private function parseString(s:String):Object
    {
        if (s == "true")
            return true;
        if (s == "false")
            return false;

        var i:int = parseInt(s);
        if (i.toString() == s)
            return i;

        var n:Number = parseFloat(s);
        if (n.toString() == s)
            return n;

        return s;
    }
}

}

////////////////////////////////////////////////////////////////////////////////
//
//  Helper class: RegistrationInfo
//
////////////////////////////////////////////////////////////////////////////////

/**
 *  @private
 */
class RegistrationInfo
{
    include "../core/Version.as";

    //--------------------------------------------------------------------------
    //
    //  Constructor
    //
    //--------------------------------------------------------------------------

    /**
     *  Constructor.
     *  
     *  @langversion 3.0
     *  @playerversion Flash 9
     *  @playerversion AIR 1.1
     *  @productversion Flex 3
     */
    public function RegistrationInfo(crc:String, depth:int)
    {
        super();

        this.crc = crc;
        this.depth = depth;
    }

    //--------------------------------------------------------------------------
    //
    //  Variables
    //
    //--------------------------------------------------------------------------

    /**
     *  @private
     */
    public var crc:String;

    /**
     *  @private
     */
    public var depth:int;
}