I used to work with a guy named Jeff. One day, a new employee?also named Jeff? joined the company. Rather than try to deal with the potential name conflicts, we simply called the new guy "Jim." This worked so well that the boss began using the name Jim on his pay envelope. If someone named Jim were to join the company, however, the naming convention would have to have been reevaluated.
Just like real-life names, service names can have conflicts. It is important that you organize server-side services in such a way that your namespaces don't collide (i.e., conflict) with other namespaces. For example, if you name your service HelloWorld, users attempting to access it might unintentionally access another HelloWorld service of the same name. This is called a namespace collision.
To avoid collisions, service names should always include the directory structure, as used in the package-naming structure of Java, where the package name relates to the domain name and project information of the package. For example, a service from Macromedia for a "Remoting" project might be named com.macromedia.Remoting. The next section describes in more detail how to create a namespace (and the directory structure it implies) that will work for examples in this book. Use this directory for all of your server-side services.
After you've installed ColdFusion, JRun, or another application server and the Flash Remoting gateway adapter, follow these steps to create your directory structure for the samples and the package structure for your remote service files:
Set up a folder on your hard drive, such as c:\frdg_samples\, in which to build the samples used in this book. You can download the finished code from the online Code Depot (cited in the Preface) and unzip them to this directory. This is the directory in which to place the .fla files for the Flash movies.
Determine the location of your root web directory (or site root directory) and make a subfolder named frdg_web within it. The example pages will run from this directory. On a typical Windows IIS server, this directory might be c:\inetpub\wwwroot\frdg_web. You can access this URL from http://localhost/frdg_web.
The server-side service files (.cfc, .dll, .class, etc.) must be placed into an appropriate location, which varies depending on the type of server you are running:
For CFCs, create the package structure as folders inside of your web root as shown in Step 4.
For ASP.NET DLLs, create the package structure in the bin folder by creating a namespace to mimic the package structure detailed in Step 4.
For Java classes, create the package structure at the root of your classpath folder as detailed in Step 4.
Set up the package structure in which to build the server-side services. For a ColdFusion Server or ASP.NET .aspx files, this package structure is simply folders under your web site root with the following subfolder structure: webroot\com\oreilly\frdg\. For the Java class files, simply create the identical structure under your classpath, which is usually in the WEB-INF (or SERVER-INF) directory in the web application.
|
The examples in this book include further instructions about these package structures and the structure of the service within the package. The service structure is explained next under Section 2.2.2.
Using this structure, you can create server-side services that are named similarly to Java packages. The com\oreilly\ portion of the path is the domain name, oreilly.com, backwards. The third subdirectory, frdg, is the project or package name. When you create your own server-side packages, you can follow this structure using your own domain name.
Using a package name that includes your domain name ensures the path to the service is unique, so you can distribute a service without worrying about namespace collisions with other services. Conversely, it ensures that third-party services you install on your server won't cause namespace collisions with your own services.
References to server-side services have different meanings depending on the environment. Table 2-8 shows the services available for different Flash Remoting environments.
Environment |
Service type |
Service path |
Methods |
---|---|---|---|
ColdFusion MX |
ColdFusion pages |
Directory path from site root |
ColdFusion page (.cfm) |
ColdFusion MX |
CFC |
Directory path from site root including ColdFusion Component (.cfc) name |
Methods of the CFC |
J2EE |
EJB |
JNDI name of the EJBHome binding |
Method of the EJB |
J2EE |
Java class |
Fully qualified Java class name |
Methods of the class |
J2EE |
JavaBean |
Fully qualified Java class name |
Methods of the JavaBean |
J2EE |
Servlet |
Directory path from site root |
Servlet |
JRun 4 |
JMX |
MBean object name |
Methods of MBean |
ASP.NET |
ASP.NET page |
Directory path from site root |
ASP.NET page (.aspx) |
ASP.NET |
DLL |
Fully qualified class name |
Methods of the DLL |
Web Services |
Web service |
URL of the .wsdl file for the service |
Methods of the remote service |
Server-Side ActionScript |
SSAS |
Directory path from the site root including the SSAS |
Methods of the SSAS (.asr) file |
PHP |
PHP page (class) |
Directory path from the services folder in the site root |
Methods of the PHP class |
To put the concept of the server-side service and package structure into context, take a ColdFusion site using the HelloWorld service from Chapter 1 as an example. I'll show how the ActionScript service object might be created using two possible types of remote services: ColdFusion (.cfm) pages and ColdFusion Components (.cfc files).
To supply remote services to your Flash movie using a ColdFusion page:
As shown in Figure 2-1, a ColdFusion .cfm file becomes the method name and the subfolder that the file is in becomes the service object path. A folder named HelloWorld will be placed in the webroot\com\oreilly\frdg directory. When creating the service object, the slashes (or backslashes) in the directory path become dots in the service's pathname, so com\oreilly\frdg\helloworld becomes com.oreilly.frdg.helloworld. This is the name via which you'll access the service object in ActionScript.
The methods of this service object, which your Flash movie calls, are ColdFusion pages in that directory (without the .cfm file extension). A ColdFusion page named sayHello.cfm would supply a remote method named sayHello( ) to your Flash movie.
In contrast to using a .cfm page, to supply a remote service using a CFC:
As shown in Figure 2-2, the CFC file path and filename (without the .cfc file extension) becomes the service object in Flash. The same example directory used earlier, webroot\com\oreilly\frdg, contains a CFC file named HelloWorld.cfc. The service object name is the same as in the .cfm example?com.oreilly.frdg.helloworld?but the service object here references a file and not a folder.
The functions defined within the CFC become the methods that you can call from the Flash movie. The method named sayHello( ) is a function inside the CFC file.
As you can see, certain types of remote services are more easily utilized with Flash Remoting. Whereas each ColdFusion page can contain only one method, requiring multiple .cfm pages in the directory, a CFC can implement many methods for a service by simply defining multiple functions within the CFC. The same holds true of an ASP.NET (.aspx) page versus the ASP.NET DLL, and a Java servlet versus a Java class or JavaBean.