Flash clients can communicate with several different service types running on a Java server. This section provides an overview of the different service types and how they are used with Flash Remoting.
Macromedia uses the term JavaBean service to refer to a Java class accessed through Flash Remoting that implements the java.io.Serializable interface (a.k.a. "implements Serializable"). While JavaBean means many things to many people, we will use Macromedia's term to identify this service type. In the case of JavaBean services, the fact that a class implements Serializable tells Flash Remoting that the service class can be stored in the user's session.
JavaBean services must have a no-argument constructor (a constructor that does not take any arguments) to be used with Remoting. If you have no other constructors, the default no-argument constructor implicit in the class is sufficient. If you have other constructors, you must explicitly implement a no-argument constructor. Otherwise, the Remoting gateway returns an error of type java.lang.InstantiationException because the gateway cannot create an instance of the service even though it can find the service class.
|
JavaBean service methods are implemented as instance methods of a JavaBean object. When the Remoting gateway invokes a JavaBean service method, it creates a new instance of the JavaBean object and invokes the service method with the arguments provided by the Flash client.
After the Remoting gateway invokes a JavaBean service, it stores the JavaBean instance in the user session and reuses it for subsequent service method calls by that same user. If the state of the JavaBean changes with one method call, the Remoting gateway uses it in its changed state for subsequent method calls. Use JavaBean services only if you want to maintain state in the Remoting service between service method calls, such as is necessary to create pageable resultsets, as discussed under Section 7.8.2 later in this chapter.
The following example shows a JavaBean service implementation with an echo( ) method that simply takes an argument and returns it back to the client. Note that this example implements java.io.Serializable and does not need to explicitly define a no-argument constructor, since it has no other constructors. When a Flash client calls echo( ), the Remoting gateway stores an instance of JavaBeanService in the session and reuses it for subsequent calls to the same service by the same client.
public class JavaBeanService implements java.io.Serializable { public Object echo (Object obj) { return obj; } }
Java class services are simply Java classes with no restrictions other than that they do not implement java.io.Serializable. Java class services must have a no-argument constructor as described for JavaBean services.
Like JavaBean services, Java class service methods are implemented as instance methods of the Java object. For each service method invocation, the Remoting gateway creates a new instance of the Java class service. The following example of a Java class service provides the same functionality as the previous JavaBean service example. The difference is that it does not implement java.io.Serializable, so the Remoting gateway creates a new instance of the Java class service each time echo( ) is called by a Flash client (recall that, in contrast, JavaBean instances are stored in the user session for subsequent service method calls by that same user):
public class JavaClassService { public Object echo (Object obj) { return obj; } }
Enterprise JavaBeans (EJBs) are the J2EE model for distributed component development. For more information on EJB design and development, refer to Enterprise JavaBeans by Richard Monson-Haefel (O'Reilly). Any EJB available to the web application within which Flash Remoting is running can be used as an EJB service. That is, you may use both remote and local entity and session EJBs as Flash Remoting services.
To use an EJB service, a Flash client identifies the service using the EJB's JNDI name (see Section 7.6.2 later in this chapter for more on JNDI names). The Flash client can then invoke any home interface method using this service. The most common use is to call create( ), but the Flash client can also call finders on entity bean home interfaces. If the result of the call on the home interface is an EJB, Flash Remoting stores that instance in the user session and sends the Flash client back a NetServices object, which can be used to call methods on that EJB.
|
Example 7-1 shows the client-side ActionScript code for using an EJB with the JNDI name java:comp/env/ejb/EjbService. The service variable is essentially a reference to the EJB home interface, and the Flash client invokes the create( ) method on it. Invoking the create( ) method creates a new instance of the EJB and passes it as the result to the create_Result( ) method on the Flash client. The create_Result( ) method then calls the echo( ) method on the EJB. Thus, we have demonstrated how to create an EJB, pass a reference to it back to Flash, and allow Flash to invoke methods on the EJB as a Remoting service itself.
// Identify the EJB with JNDI name "java:comp/env/ejb/EjbService" var service = gatewayConnection.getService("java:comp/env/ejb/EjbService", this); // Create an instance of the EJB service.create( ); // The result handler for create( ) receives a reference to the EJB function create_Result(ejb) { // Call echo on the created EJB ejb.echo("Flash says 'say hi.'"); } // Handle the result of calling echo( ). function echo_Result(result) { trace("The EJB said " + result); }
Servlet services are simply servlets running in the web application container. A Flash client uses a servlet service by using the web application context name as the service name and the servlet name, as it is identified in the web.xml file, as the service method name. For example, consider a web application named remotingbook and a servlet named ServiceServlet mapped in its web.xml file:
<servlet> <servlet-name>ServiceServlet</servlet-name> <servlet-class> com.oreilly.frdg.java.service.ServiceServlet </servlet-class> </servlet>
Example 7-2 shows the client-side ActionScript code, which creates a service object by specifying the web application name in quotes ("remotingbook") as the service name. It then invokes the servlet service as a method of the service object returned by getService( ).
// The web application name is used as the service name var service = gatewayConnection.getService("remotingbook", this); // Call the servlet service as a method of the service object service.ServiceServlet("Hello."); // Handle the service servlet result function ServiceServlet_Result(result) { trace("ServiceServlet_Result:" + result); }
Example 7-3 shows a servlet service that accepts an argument list from a Flash client and, for demonstration purposes, simply returns the same arguments back to Flash. The servlet service receives the Flash arguments via the FLASH.PARAMS attribute of the request object. It returns a result by setting the FLASH.RESULT attribute of the request object:
public class ServiceServlet extends HttpServlet { public void service(HttpServletRequest request, HttpServletResponse response) throws ServletException { // Retrieve the parameter list from the Flash invocation of ServiceServlet( ) List params = (List) request.getAttribute("FLASH.PARAMS"); // Just echo the parameters back to Flash request.setAttribute("FLASH.RESULT", params); } }
There is always a java.util.List in request.getAttribute("FLASH.PARAMS"). If the Flash client provides no arguments in the service method call, the List is empty.
Macromedia provides a servlet implementation, flashgateway.adapter.java.FlashServlet, that handles fetching the parameters from and setting the results in the request object's attributes. The following example shows a ServiceFlashServlet class, which extends FlashServlet to replicate the functionality of Example 7-3. The FlashServlet.service( ) method accepts a list of parameters from Flash and returns an object as the result. The ServiceFlashServlet.service( ) method does not throw any exceptions, so if you need to throw a checked exception (an exception that must be caught somewhere in the call chain) from your servlet service, you must implement your servlet service manually, as shown in the Example 7-3. Adding a checked exception when extending a method will cause a compiler error.
import flashgateway.adapter.java.FlashServlet; public class ServiceFlashServlet extends FlashServlet { public Object service (ServletRequest request, ServletResponse response, List params) { // Just echo the parameters back to Flash return params; } }
In application servers that support the Servlet 2.3 specification, you can configure JSPs as servlets in your web.xml file as follows:
<servlet> <servlet-name>JspService</servlet-name> <jsp-file>/WEB-INF/jsp/service/jspService.jsp</jsp-file> </servlet>
With this configuration, you can use the JSP file as a Remoting service in the same way you used a servlet as a service. Here is what the client-side ActionScript code looks like:
// The web application name is used as the service name var service = gatewayConnection.getService("remotingbook", this); // Call the JSP service service.JspService ("Hello."); // Handle the JSP servlet result function JspService_Result(result) { trace("JspService_Result:" + result); }
Here is the server-side code in jspService.jsp:
<%@ page language="java"%> <% // Retrieve the parameters sent from Flash java.util.List params = (java.util.List) request.getAttribute("FLASH.PARAMS"); // Just echo the parameters back to Flash request.setAttribute("FLASH.RESULT", params); %>
Servlet services are awkward to use because the service method arguments and result must be accessed through attributes of the request object. Additionally, developers must implement a new servlet for each service method they provide to the Flash client. However, servlet services are the only service type that has direct access to the user request and, therefore, the user session. This access can be very helpful for developers who need to access, from Remoting services, information that has been stored in the user session by other objects running in the application.
The Java Management Extensions (JMX) is an optional extension to the core Java technologies that standardizes management interfaces to remote services. Typically, it is used to manage services running in a J2EE application server. A managed bean (MBean) is a Java object that represents a JMX manageable resource. For more information on JMX and MBeans, see http://java.sun.com/products/JavaManagement.
When used with JRun, Flash Remoting gives Flash clients direct access to MBeans running in JRun as MBean services. With access to these MBeans, a Flash client can inspect the state of services deployed in JRun.
SSAS is not a standard J2EE technology. It is a feature of JRun and ColdFusion. When used with JRun and ColdFusion, Flash Remoting gives Flash clients the ability to invoke methods on SSAS objects.
Server-Side ActionScript is covered in detail in Chapter 6 and is not addressed in this chapter.