7.6 Service Lookup

This section describes the process for identifying, locating, and invoking services through the Remoting gateway.

When multiple services methods are invoked in a single frame of a Flash movie, Remoting on the Flash client aggregates multiple service method calls in a single HTTP request. On the server, The Remoting gateway handles each service method call individually. The following discussion applies to both individual and aggregated service method calls.

7.6.1 Identifying Services

When a Flash client connects to a service using NetConnection.getService( ), the gateway tries to locate the named service that is passed as the first argument. For JavaBean and Java class services, the service name (or, more formally, the service identifier) is the full class name, including the package, of the service implementation class. This ActionScript example creates a service reference to a Java class service with class name "com.oreilly.frdg.java.JavaClassService":

var service = gatewayConnection.getService(
                  "com.oreilly.frdg.java.JavaClassService", this);

For EJBs, the service name is the JNDI name of the EJB as it is accessed from within the servlet container. The following ActionScript example creates a service reference to an EJB service with JNDI name "java:comp/env/ejb/EjbService".

var service = gatewayConnection.getService(
                  "java:comp/env/ejb/EjbService", this);

For servlets, the service name is the web application context name (i.e., the URL prefix that identifies your web application). The following ActionScript example creates a service reference to the web application named mywebapp. The service name does not include any servlet services that may invoked on the service object reference at a later time.

var service = gatewayConnection.getService("mywebapp", this);

For MBeans, the service name is the name of the JMX object under which the MBean is registered. This ActionScript example creates a service reference to an MBean named DeployerService in the DefaultDomain MBean server. The format of this identifier is defined by the JMX standards.

var service = gatewayConnection.getService(
                  "DefaultDomain:service = DeployerService", this);

7.6.2 Locating Services

Calling gatewayConnection.getService( ) does not result in the Flash client communicating with the server. The Flash client doesn't contact the server until the client-side ActionScript makes the first method call on the service. When the Remoting gateway receives the first service method call, it tries to locate the service. If it is found, the gateway tries to invoke the specified service method on it on behalf of the Flash client. Because they are two separate steps, the gateway may succeed in finding the service but fail to invoke the service method.

The gateway uses the service identifier to locate services in the following order:

For platforms in which a particular service type is not supported, the gateway does not try to locate a service of that type. For example, Flash Remoting does not support EJBs when running on Sun ONE Web Server, so the gateway would not look for EJB services in that case.

The gateway identifies JavaBean services by looking for the identified class in the classpath of the gateway's classloader. If it finds the class and the class implements java.io.Serializable, the gateway uses the JavaBean as the service.

Classloaders in J2EE web applications can get interesting. A classloader is responsible for locating Java classes in its classpath. In an application server, classloaders have a hierarchy. Each web application has a classloader with a classpath specific to that web application. If the web application classloader can not find a class, the next classloader above it tries to locate the class within its classpath, and so on until either the class is found or all classloaders in the hierarchy have failed to find the class.

Our installation instructions for Flash Remoting recommend installing the flashgateway.jar file in the WEB-INF/lib directory of your web application. In this location, the Remoting gateway uses the classloader for your web application when trying to locate Java classes. It will be able to locate all classes in your web application and in the classpath of all classloaders above your web application. If you install flashgateway.jar in another location?say, the classpath of your application server?it will not be able to see classes in classloaders lower in the hierarchy and will therefore fail to find services implemented by those classes.

If the gateway does not find a JavaBean service, it simply looks for the identified class in the classpath of the gateway's classloader. It uses the class as a Java class service if it finds it.

The gateway next looks for an EJB in JNDI using the service identifier. JNDI (Java Naming and Directory Interface) is the standard J2EE interface for organizing and locating objects regardless of their actual location. The entry point to JNDI is an InitialContext object. The Remoting gateway uses the default InitialContext returned by new InitialContext( ) to look up the EJB. Configuration of your default InitialContext depends on your application server platform. Basically, the JNDI name you use to look up the EJB from within a servlet in your web application is the JNDI name to use as the service identifier in Flash. If the gateway finds the named EJB in JNDI, it uses the named EJB as the service.

The gateway next looks for servlet services by first locating a web application ServletContext object with same name as the service identifier. If it finds the ServletContext, the gateway then looks for a servlet with the same name as the service method in that ServletContext. If it finds both the named ServletContext and the servlet, the gateway uses the servlet as the service. As described in "Servlet Services" earlier in this chapter, the name of the service method in ActionScript must match the name of a servlet defined in your application's web.xml file.

This example shows a servlet named ServiceServlet:

<servlet>
 <servlet-name>ServiceServlet</servlet-name>
 <servlet-class>
   com.oreilly.frdg.java.service.ServiceServlet
 </servlet-class>
</servlet>

If the gateway is running in JRun and the service has not been found yet, the Remoting gateway continues trying to locate the service by next looking for a JMX MBean. It looks for an MBean with the name provided as the service identifier in Flash. If it finds the MBean, the gateway uses it as the service.

Finally, if it has found none of the other service types and it is running in JRun, the gateway looks for a Server-Side ActionScript service. The gateway locates the SSAS service by mapping the dot-separated service identifier to a file path that the gateway looks for, relative to the web application root. Using Example 6-7, the SSAS service com.oreilly.frdg.Directory maps to the file com/oreilly/frdg/Directory.asr in the web application root. If it finds the file, the gateway uses it as the service. Note that the gateway ignores SSAS services in the protected WEB-INF and META-INF directories.

If the gateway is unable to find a service with the name identified by the Flash client, it throws a flashgateway.adapter.NoSuchServiceException, which is returned to Flash's onStatus( ) handler as an error object. The description property of the error object includes the name of the service it was trying to find.