4.1. Scripting Application Instances

When double-byte characters are required, such as for Kanji, you must use a text editor capable of handling UTF-8 encoding. In addition, method names containing higher-order double-byte characters must use the array operator instead of the dot operator. For example:

obj = {};
obj.myMethodName = function (  ) {
  trace("myMethodName");
};
obj["myMethodName"]( ); // Correct
obj.myMethodName( );    // Correct

obj["
"] = function ( ) {
  trace("
");
};
obj["
"]( );    // Correct
obj.
( );       // Syntax Error !!

4.1.1. Instances and Resources

FlashCom can run multiple instances of an application at the same time. Each instance has its own memory, disk, stream, and shared object environment and runs its own single-threaded copy of the main.asc script. Instances are an important way to group users and partition the server's resources among them. Perhaps the simplest example of this is a chat application. Many instances of a chat application can be run simultaneouslyeach with different users connected to iteffectively creating a set of chat rooms. Users who connect to rtmp:/courseChat/room1 can communicate with each other using the streams and shared objects associated with the room1 instance. Other users who connect to rtmp:/courseChat/room2 can communicate among themselves using the room2 instance but will normally be unaware of the conversation occurring in the room1 instance. If instances must share streams or shared objects, one instance can make a network connection to another to gain access to its resources.

Although you can build an application in which a single instance provides a lobby and multiple chat rooms simultaneously, it's not recommended. If a large number of users simultaneously use a single instance, performance suffers. Because an instance's ActionScript runs in a single thread, every remote method call on the server, including the delivery of chat messages, will execute sequentially.

It is difficult to give precise limits on how many clients are too many for one instance because each application makes different demands on the server. An instance that makes extensive use of Server-Side ActionScript may support fewer than 20 clients with adequate performance, while other applications may support hundreds or even a few thousand. Chapter 16 covers architectures that scale more effectively.

The streams and shared objects available to each instance are located by FlashCom using a relative URI. Most often this is just the name of the stream or shared object. For example, if a Flash movie plays a stream named intro, then "intro" is a relative URI to the instance to which the movie is connected. If the instance URI is:

rtmp://my.university.edu/courseLectures/algebra101

then the full URI to the intro video would be:

rtmp://my.university.edu/courseLectures/algebra101/intro

In practice, a full URI like that is never used, but it is useful to think of stream and shared object resources as existing in a space defined by full URIs. We'll make use of full URIs later in this chapter to show how streams are organized within an application. A Flash movie requests resources associated with an application instance using a relative URI after a connection has been attempted. For example, a movie must first request a connection to an instance before trying to publish or play a stream or get a remote shared object:

nc.connect("rtmp://my.university.edu/courseLectures/algebra101");

Once the connection has been attempted, the Flash movie can request that a recorded or live stream named intro be played:

ns = new NetStream(nc);      // Create a NetStream within a NetConnection.
videoArea.attachVideo(ns);   // Attach the stream to a video object on the Stage.
ns.play("intro");            // Play a stream named intro.

Similarly, a shared object named streamList, which contains a list of stream names, may be available for the algebra101 instance. After a connection is requested to the algebra101 instance, access to the streamList shared object could be requested as follows:

so = SharedObject.getRemote("streamList", nc.uri, true);
so.onSync = function (list) {
  trace("onSync> list.length: " + list.length);
};
so.connect(nc);

The NetStream and SharedObject classes are described in detail in Chapter 5 and Chapter 8. In both previous examples, the name of the stream and the shared object are simple relative URIs. The relative path to a stream or shared object within an instance can include directory-like names that help to separate resources into groups. For example, lectures can be grouped by subject so that a relative URI to a video stream might be vectors/intro while there is another video located at matrices/intro. A client-side play( ) method call for one of these examples would look like this:

ns.play("vectors/intro");

Similarly, a shared object available at the relative URI vectors/quizQuestions would be created like this:

so = SharedObject.getRemote("vectors/quizQuestions", nc.uri, true);

Drawing a simple directory tree showing the resources within an instance is a good idea when developing an application. Figure 4-1 shows the location and relative URI of resources for the algebra101 instance of the courseLectures application.

Figure 4-1. Relative URIs for resources within the algebra101 instance

All recorded streams and persistent shared object files are normally stored in the streams and sharedobjects directories in an application's home directory. The two directories are organized in a hierarchy that is consistent with the relative URI addressing of instance resources. If the streams and shared objects of this example are stored on the server, they will be found within the directory structure illustrated in Figure 4-2.

Figure 4-2. Shared object and stream file locations

Instance names such as algebra101 appear as top-level directories within the stream and sharedobjects directories. Within instance name directories, such as algebra101, are the directories and files that conform to the relative URIs used for them in Figure 4-1. For example, a stream that is recorded to the algebra101 instance's relative URI vectors/intro, will have a file path of:

.../applications/courseLectures/streams/algebra101/vectors/intro.flv

Streams can be shared by all application instances by defining a special virtual directory. See "Uploading Prerecorded Streams" in Chapter 5 for more information.

4.1.2. Resource Name Collisions

In theory, each instance manages its own stream and shared object resources without interference from other instances. In one important case, however, stream and shared object instance names can collide (i.e., two different instances attempt to use the same resource); naturally, you want to avoid such collisions. Using the previous example of a courseLectures application, imagine that one client connects to this URI:

rtmp:/courseLectures/algebra101

and a second client connects to a different URI:

rtmp:/courseLectures/algebra101/vectors

This will start two instances of the courseLectures application: one instance named algebra101 and the other named algebra101/vectors. If the first instance attempts to access a shared object at the relative URI of vectors/quizQuestions and the second attempts to access a shared object at the relative URI of quizQuestions, they will both be using the same quizQuestions shared object at the full URI of:

rtmp:/courseLectures/algebra101/vectors/quizQuestions

FlashCom is not designed to handle this situation.

Two instances should never directly attempt to update the same shared object. If more than one instance needs to use a shared object, it should be done via a NetConnection between the instances.

Usually, one instance is selected as the owner of the shared object or stream and the other instances connect to it in order to access its resources. Interinstance communications is covered in detail later in this chapter and in Chapter 16.