2.2 Naming Your Services

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.

2.2.1 Creating the Sample Directories and Package Structure

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:

1. 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.

2. 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 .

3. 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:

   1. For CFCs, create the package structure as folders inside of your web root as shown in Step 4.

   2. 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.

   3. For Java classes, create the package structure at the root of your classpath folder as detailed in Step 4.

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.

In order for the package structure to work properly, it needs to begin at the site root for ColdFusion, at the bin folder for ASP.NET, and at the root of the classpath for Java classes. If your web host has given you a folder under a site root but has not set up a virtual directory for you, the package will not work. Make sure a virtual directory has been created, or use an appropriate package path based on the physical location of the folders on the hard drive.

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.

2.2.2 The 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.

Table 2-8. Service types available to the Flash Remoting programmer

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.

Figure 2-1. A subfolder becomes the remote service, and the ColdFusion page becomes the remote method

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.

Figure 2-2. A ColdFusion Component becomes the remote service and the function inside becomes a method

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.