4.4. Running a Simple Hello World Test Script

Example 4-2 shows a short main.asc script that is the SSAS implementation of helloWorld. It demonstrates all the standard event handler methods of the application object.

Example 4-2. A simple server-side helloWorld test script

application.onAppStart = function (  ) {
   trace("onAppStart> " + application.name + " is starting at " + new Date( ));
};

application.onStatus = function (info) {
   trace("onStatus> info.level: " + info.level + ", info.code: " + info.code);
   trace("onStatus> info.description: " + info.description);
   trace("onStatus> info.details: " + info.details);
};

application.onConnect = function (client, userName, password) {
   client.userName = userName;
   client.writeAccess = "/public";
   client.readAccess  = "/";
   application.acceptConnection(client);
   trace("onConnect> client.ip: " + client.ip);
   trace("onConnect> client.agent: " + client.agent);
   trace("onConnect> client.referrer: " + client.referrer);
   trace("onConnect> client.protocol: " + client.protocol);
};

application.onDisconnect = function (client) {
   trace("onDisconnect> client.userName: " + client.userName)
   trace("onDisconnect> disconnecting at: " + new Date( ));
};

application.onAppStop = function (info) {
   trace("onAppStop> application.name: " + application.name);
   trace("onAppStop> stopping at " + new Date( ));
   trace("onAppStop> info.level: " + info.level);
   trace("onAppStop> info.code: " + info.code);
   trace("onAppStop> info.description: " + info.description);
};

With this example code in mind, let's take a closer look at the most important event handling methods of the application object. These are invoked automatically when the application starts, when a client attempts to connect, when a client disconnects, or when the application is supposed to shut down.

4.4.1. application.onAppStart( )

When an application instance is accessed the first time, the script is compiled and any global code (i.e., code outside the context of an event handler) is executed. After that, the application.onAppStart( ) method is called. In Example 4-2, the application.name property is used to output the name of the instance that has been started. The name will always be in the format appName/instanceName. For example, "helloWorld/_definst_" is the default instance name for the helloWorld application. If an instance name includes directories, the name property may contain a string such as "courseChat/chem101/room1".

4.4.2. application.onStatus( )

The application.onStatus( ) method receives messages for server-side Stream and NetConnection objects that do not have onStatus( ) handlers, in addition to other application messages. The onStatus( ) handler is not invoked in Example 4-2, but the handler declaration is included to show the information object properties that can be received.

4.4.3. application.onConnect( )

The application.onConnect( ) method shows the interaction between the application object and the client object passed into it. The client object is an instance of the Client class, which provides information about the Flash movie attempting a connection, such as its IP address. An instance of the Client class is always passed into the onConnect( ) method. In this example, each instance is named client. The difference in capitalization means that there is no name conflict between the Client class name and the individual client object passed into onConnect( ). If you find this confusing or want to use a naming convention that is consistent with how you write code in Flash MX, then instead of using client as an object name, use something like newClient:

application.onConnect = function (newClient, userName, password) {
  newClient.userName = userName;
  application.acceptConnection(newClient);
};

Along with the IP address (the ip property), each client has properties that contain the name of the user agent, referring page, and connection protocol. Other properties of the client object include readAccess and writeAccess, which can be used to control what relative URIs the client can access, and therefore what streams and shared objects are available to each client. In Example 4-2, the client is allowed to write to any resource in the public directory or its subdirectories because writeAccess is "/public". The client is allowed to read (access) any resource in any directory because readAccess has been set to "/", which is the root of any relative URI within the instance.

Properties can be added to the client object; in this example, a userName property is added dynamically. The userName variable passed into the onConnect( ) method is the name with which the user logged in; the code stores it as a propertyalso named userNameof the client object so that it is available even after the onConnect( ) handler exits.

The onConnect( ) handler in Example 4-2 allows the client to connect to the application instance by invoking application.acceptConnection( ). Client connection requests can also be rejected using application.rejectConnection( ). Calling these methods inside onConnect( ) is not really necessary. If onConnect( ) returns true, the client connection is accepted; the connection is rejected if onConnect( ) returns false. More importantly, if onConnect( ) returns nothing or null, the client is left in a pending state and is unable to communicate with the server. Connections for pending clients can still be accepted or rejected outside of the onConnect( ) method by calling application.acceptConnection( ) or application.rejectConnection( ).

If the application.onConnect( ) method is not defined, all client connections are accepted and all clients are given global read and write access equivalent to setting readAccess and writeAccess to "/".

4.4.4. application.onDisconnect( )

The application.onDisconnect( ) method is called when FlashCom detects that a client with an accepted or pending connection has disconnected from the instance. In the example, the client.userName property is used to identify who is leaving.

4.4.5. application.onAppStop( )

Finally, application.onAppStop( ) is called just before the instance is shut down. It is passed an information object that specifies the reason for the shutdown; it can prevent the instance from shutting down by returning false.

4.4.6. Using the App Inspector to Run Scripts

To try out a script like the one in Example 4-2, create a text file named main.asc (or download it from the book's web site) and save it into a subdirectory of your applications folder named helloWorld. Find the app_inspector.swf movie (located in FlashCom 1.5's flashcom_help/html/admin directory). This .swf is a testing tool known as the App Inspector.

Start the app_inspector.swf movie by opening it in the Flash Player, or load the app_inspector.html page into your browser and enter the location of the server in the Host field. If you are running FlashCom on your workstation, enter localhost in the Host field. If FlashCom is running on a remote server, enter the server's IP address or hostname. In the Name and Password fields, enter the administrator's username and password, which you chose during FlashCom's installation procedure.

After connecting, enter helloWorld in the App/Inst field and click the Load button, as shown in Figure 4-3. If the instance doesn't load, an information icon should appear near the Load button. Click on it to see what went wrong, fix and resave your script if necessary, and try again.

Figure 4-3. Loading an application in the App Inspector following login

If the helloWorld/_definst_ instance is not loaded successfully, click on the View Detail button, as shown in Figure 4-4.

Figure 4-4. The App Inspector after loading a helloWorld application

If the helloWorld/_definst_ instance is loaded successfully, click on the Live Log tab of the App Inspector. Click the Reload App button to force the instance to restart so that you can see the output from the test script's application.onAppStart( ) method.

Figure 4-5 shows the output in the Live Log area of the App Inspector after the helloWorld application was restarted.

Figure 4-5. The App Inspector after restarting helloWorld/_definst_

The log shows the application instance was shut down and restarted, but the messages do not appear in the order you might expect. System messages and trace( ) messages from the script are often intermixed. For example, the system message "Loading of app instance: helloWorld/_definst_ successful" appears in between messages generated by the trace( ) function while the instance was unloading in the onAppStop( ) method. The messages generated by the script in the previous output listing occur only in the onAppStart( ) and onAppStop( ) methods. To see messages related to clients connecting and disconnecting from the application instance requires a movie that connects to and disconnects from the instance. For this purpose, a test movie is supplied on the book's web site as part of the helloWorld.zip archive. Test movies are an important tool. A good but simple test movie should allow you to:

• Enter or select different application instance names to which to connect

• Enter a username and password or other connection parameters

• Read all the status and error messages the client receives or generates

• Easily extend it to add features as necessary

The output in Figure 4-6 shows the Live Log area when a connection is made and then dropped from a client. The IP address of 127.0.0.1 indicates that the client was running on the same system as the FlashCom Server.

Figure 4-6. The App Inspector after a client connects to and disconnects from helloWorld/_definst_

Twenty-three minutes after the client disconnected, the instance shuts down and produces the output shown in Figure 4-7 in the App Inspector.

Figure 4-7. The App Inspector after the helloWorld/_definst_ instance shuts down

The output in the Live Log area of the App Inspector shows data such as startup and shutdown times, the client IP address and username, and when the client connects and disconnects. The App Inspector and server-side trace( ) statements are essential for testing and debugging server-side scripts.