Summary

Contains Command class.

This is part of Troika.ASP Framework - web development MVC framework for ASP 3.0. Please visit www.troika-asp.com for more details.

/**
* @fileoverview Contains <tt>Command</tt> class.
*
* <p>
* This is part of Troika.ASP Framework - web development MVC framework for ASP 3.0.
* Please visit {@link http://www.troika-asp.com www.troika-asp.com} for more details.
* </p>
*
* @author Pavel Chuchev pav@troika-asp.com
* @version $Revision: 1.4 $
*/
/**
* Constructs a new instance of Command class.
*
* @class This is <tt>Command</tt> class the base class for all user defined commands.
*
* @constructor
* @param {Config} config The instance of <tt>Config</tt> class.
*/
function Command(config) {

    if (arguments.length) {

        this.init(config);
    }
}
/**
* Initializes <tt>Command</tt>.
*
* @param {Config} config The XSL template file to transform.
* @return <tt>Command</tt> object instance itself.
* @type Command
*/
Command.prototype.init = function (config) {

    this.config = config;

    return this;
};
/**
* Searches Command mappings from config.xml for Forward object and returns it if found.
* It throws errors if the Forward object could not be located.
*
* <p>For example we can this Command definition in config.xml:</p>
* <pre>
*         &lt;cmd-map action="secretAction"&gt;
*             &lt;name>secretForm&lt;/name&gt;
*             &lt;type>SecretAction&lt;/type&gt;
*             &lt;forwards&gt;
*                 &lt;forward name="success" redirect="false"
*                          path="/views/secret.xsl"/&gt;
*             &lt;/forwards&gt;
*         &lt;/cmd-map&gt;
* </pre>
*
* <p>In execute() method of the Command object we would call:</p>
*
* <pre>
*
* var forward = this.findForward(secretForm, "success");
*
* //change the forward fields
* forward.redirect = true;
* forward.path = "/views/secret2.xsl";
*
* </pre>
*
* @param {RequestContext} requestCxt The RequestContext instance.
* @param {String} forwardName The name of the <tt>Forward</tt> declaration.
* @return The instance of Forward. A Forward object is indirect handle to view.
* @type Forward
* @throw The method throws the following errors if it cannot locate the forward by name:
* <ul>
* <li>Action {requestCxt.action} not defined in Config.xml</li>
* <li>Forward {forwardName} not found for {requestCxt.action} action</li>
* </ul>
*/
Command.prototype.findForward = function (requestCxt, forwardName) {

    var cmdMaps = this.config.cmdMaps;

    var map = cmdMaps[requestCxt.action];
    if (!map) {

        throw new Error("Action '" + requestCxt.action + "' not defined in Config.xml");
    }

    var result = map.forwards[forwardName];
    if (!result) {

        throw new Error("Forward '" + forwardName + "' not found for '" + requestCxt.action + "' action");
    }

    return result;
};

/**
* Performs business logic and returns responseContext
*
* @param {Environment} environment The instance of <tt>Environment</tt> class.
* @param {RequestContext} requestCxt The instance of <tt>RequestContext</tt> class.
* @return The instance of ResponseContext or <tt>undefined</tt> if this methis handles the output itself.
* @type ResponseContext
*/
Command.prototype.execute = function (environment, requestCxt) {

};
/**
* Logs error message to application log file. The <tt>error</tt> parameter will be queried and broken
* into name/value pairs before being written into the log file.
*
* <p>Log file configuration is specified in config.xml:</p>
* <pre>
*    &lt;logger&gt;
*         &lt;file-name&gt;${root}/WEB-INF/logs/application.log&lt;/file-name&gt;
*         &lt;max-size&gt;1024&lt;/max-size&gt;
*         &lt;generations&gt;2&lt;/generations&gt;
*         &lt;log-level&gt;FILTER_INFO&lt;/log-level&gt;
*     &lt;/logger&gt;
* </pre>
* <pre>
* The code like this:
*
*     this.logError("Error1");
*     this.logError(secretForm);
*
*
* Will produce the output in application.log as follows:
*
* [2007/03/23 10:15:27] {E} TRAN ID - 1174644927701-1 {E} Error1
* [2007/03/23 10:15:27] {E} TRAN ID - 1174644927701-2 {E} action=secretAction |
* </pre>
*
* @param {Object} error The error object.
*/
Command.prototype.logError = function (error) {

    var msg = error;

    if (typeof (error) == "object") {

        msg = "";

        for (key in error) {

            if (typeof (error[key]) == "string") {

                msg += key + "=" + error[key] + " | ";
            }
        }
    }

    Logger.log.error(msg);
};
/**
* Logs info message to application log file.
*
* <p>Log file configuration is specified in config.xml:</p>
* <pre>
*    &lt;logger&gt;
*         &lt;file-name&gt;${root}/WEB-INF/logs/application.log&lt;/file-name&gt;
*         &lt;max-size&gt;1024&lt;/max-size&gt;
*         &lt;generations&gt;2&lt;/generations&gt;
*         &lt;log-level&gt;FILTER_INFO&lt;/log-level&gt;
*     &lt;/logger&gt;
* </pre>
* <pre>
* The code like this:
*
*     //create an object dynamically
*     var obj2 = {};
*     obj2.prop1 = 100;
*     obj2.prop2 = "value2";
*
*     this.logInfo(obj2);
*     this.logInfo(obj2.toXML());
*
* Will produce the output in application.log as follows:
*
* [2007/03/23 10:15:27] {I} TRAN ID - 1174644927701-4 {I} {"prop1":100,"prop2":"value2"}
* [2007/03/23 10:15:27] {I} TRAN ID - 1174644927701-5 {I} <Object>
*    <prop1>100</prop1>
*    <prop2>value2</prop2>
* </Object>
* </pre>
*
* @param {String} msg The info message.
*/
Command.prototype.logInfo = function (msg) {

    Logger.log.info(msg);
};
/**
* Logs warning message to application log file.
*
* <p>Log file configuration is specified in config.xml:</p>
* <pre>
*    &lt;logger&gt;
*         &lt;file-name&gt;${root}/WEB-INF/logs/application.log&lt;/file-name&gt;
*         &lt;max-size&gt;1024&lt;/max-size&gt;
*         &lt;generations&gt;2&lt;/generations&gt;
*         &lt;log-level&gt;FILTER_INFO&lt;/log-level&gt;
*     &lt;/logger&gt;
* </pre>
* <pre>
* The code like this:
*
*     this.logWarn("Warning1");
*
* [2007/03/23 10:15:27] {W} TRAN ID - 1174644927701-3 {W} Warning1
* </pre>
*
* @param {String} msg The warning message.
*/
Command.prototype.logWarn = function (msg) {

    Logger.log.warning(msg);
};

/**
* Looks up database connection string from Config class and return it.
*
* <p>In our config.xml:</p>
* <pre>
* &lt;db-connection name="helloworld-db"
*                        conn-string="Driver={Microsoft Access Driver (*.mdb)};Dbq=${root}/WEB-INF/data/helloworld.mdb;"/&gt;
* </pre>
* <pre>
*
* var connStr = this.getConnectionString("helloworld-db");
*
* </pre>
*
*
* @param {String} dbName The name of the database to lookup.
* @reteurn The database connection string.
* @type String
*/
Command.prototype.getConnectionString = function (dbName) {

    return this.config.dBConnections[dbName];
};