You declare RemoteObject components in MXML or ActionScript to connect to remote services. Use the RemoteObject component to call methods on a Java class or ColdFusion component.

A destination for a RemoteObject component is a Java class defined as the source of a Remoting Service destination. Destination definitions provide centralized administration of remote services. They also enable you to use basic or custom authentication to secure access to destinations. You can choose from several different transport channels, including secure channels, for sending data to and from destinations. Additionally, you can use the server-side logging capability to log remote service traffic.

You can also use RemoteObject components with PHP and .NET objects in conjunction with third-party software, such as the open source projects AMFPHP and SabreAMF, and Midnight Coders WebORB. For more information, see the following websites:

• AMFPHP http://amfphp.sourceforge.net/
• SabreAMF http://www.osflash.org/sabreamf
• Midnight Coders WebORB http://www.themidnightcoders.com/

Remoting Service channels

With the Remoting Service, you often use an AMFChannel. The AMFChannel uses binary AMF encoding over HTTP. If binary data is not allowed, then you can use an HTTPChannel, which is AMFX (AMF in XML) over HTTP. Message channels are typically defined in the services-config.xml file, in the channels section under the services-config element. For more information on channels, see LiveCycle Data Services ES architecture.

Using a RemoteObject component

The following example shows a RemoteObject component that connects to a destination, sends a request to the data source in the click event of a Button control, and displays the result data in the text property of a TextArea control:

<?xml version="1.0"?>
<!-- ds\rpc\RPCIntroExample1.mxml --> 
<mx:Application xmlns:mx="http://www.adobe.com/2006/mxml">

    <mx:Script>
        <![CDATA[
            import mx.rpc.events.ResultEvent;
            import mx.rpc.events.FaultEvent;
            import mx.controls.Alert;
            
            public function handleResult(event:ResultEvent):void {
                // Handle result by populating the TextArea control.
                outputResult.text=remoteService.getData.lastResult.prop1;
            }                       
            
            public function handleFault(event:FaultEvent):void {
                // Handle fault.
                Alert.show(event.fault.faultString, "Fault");               
            }
        ]]>
    </mx:Script>

    <!-- Connect to a service destination.--> 
    <mx:RemoteObject id="remoteService" 
        destination="census"
        result="handleResult(event);"
        fault="handleFault(event);"/>

    <!-- Provide input data for calling the service. --> 
    <mx:TextInput id="inputText"/>

    <!-- Call the web service, use the text in a TextInput control as input data.--> 
    <mx:Button click="remoteService.getData(inputText.text)"/>

    <!-- Display results data in the user interface. --> 
    <mx:TextArea id="outputResult"/>
</mx:Application>

Added 1/07/09:
Note: The RemoteObject.endpoint property lets you quickly specify an endpoint for a RemoteObject destination without referring to a services configuration file at compile time or programmatically creating a ChannelSet object. It also overrides an existing ChannelSet if one has been set for the RemoteObject. If the endpoint url starts with "https", a SecureAMFChannel will be used, otherwise an AMFChannel will be used. Two special tokens, {server.name} and {server.port}, can be used in the endpoint url to specify that the channel should use the server name and port that was used to load the SWF.

Defining remote Java objects

One difference between Remoting Service destinations and HTTP service and web service destinations is that in Remoting Service destinations you host the remote Java object in your LiveCycle Data Services ES web application and reference it by using a destination. With HTTP service and web service destinations, you typically configure the destination to access a remote service, external to the web application. A developer is responsible for writing and compiling the Java class and adding it to the web application classpath by placing it in the WEB-INF\classes or WEB-INF\lib directory.

You can use any plain old Java object (POJO) that is available in the web application classpath as the source of the Remoting Service destination. The class must have a zero-argument constructor so that LiveCycle Data Services ES can construct an instance.

The following example shows a Remoting Service destination definition in the remoting-config.xml file. The source element specifies the fully qualified name of a class in the classpath of the web application.

<destination id="census">
    <properties>
        <source>flex.samples.census.CensusService</source>
    </properties>

</destination>

The following example shows the corresponding source code of the Java class that is referenced in the destination definition:

package flex.samples.census;

import java.util.ArrayList;
import java.util.List;
import java.sql.Connection;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.sql.SQLException;

import flex.samples.ConnectionHelper;

public class CensusService
{
    public List getElements(int begin, int count)
    {

        long startTime = System.currentTimeMillis();

        Connection c = null;
        List list = new ArrayList();

        String sql = "SELECT id, age, classofworker, education, maritalstatus, race, 
            sex FROM census WHERE id > ? AND id <= ? ORDER BY id ";

        try {

            c = ConnectionHelper.getConnection();
            PreparedStatement stmt = c.prepareStatement(sql);
            stmt.setInt(1, begin);
            stmt.setInt(2, begin + count);
            ResultSet rs = stmt.executeQuery();

            while (rs.next()) {
                CensusEntryVO ce = new CensusEntryVO();
                ce.setId(rs.getInt("id"));
                ce.setAge(rs.getInt("age"));
                ce.setClassOfWorker(rs.getString("classofworker"));
                ce.setEducation(rs.getString("education"));
                ce.setMaritalStatus(rs.getString("maritalstatus"));
                ce.setRace(rs.getString("race"));
                ce.setSex(rs.getString("sex"));
                list.add(ce);
            }
        } catch (SQLException e) {
            e.printStackTrace();
        } finally {
            try {
                c.close();
            } catch (Exception ignored) {
            }
        }

        return list;
    }
}

Placing Java objects in the classpath

The Remoting Service lets you access stateless and stateful objects that are in the classpath of the LiveCycle Data Services ES web application. Place class files in the WEB-INF\classes directory to add them to the classpath. Place Java Archive (JAR) files in the WEB-INF\lib directory to add them to the classpath.

Specify the fully qualified class name in the source property of a Remoting Service destination in the remoting-config.xml file. The class also must define a constructor that takes no arguments.

Converting ActionScript data to and from Java data

When you send data from a Flex application to a Java object, the data is automatically converted from an ActionScript data type to a Java data type. An object returned from a Java method is converted from Java to ActionScript. For a complete description of how data is converted, see Data serialization.

Reserved method names for the RemoteObject component

If a remote method has the same name as a method defined by the RemoteObject class, or by any of its parent classes, then you cannot call the remote method directly. The RemoteObject class defines the following method names; do not use these names as method names in your Java class:

disconnect()
getOperation()
hasOwnProperty()
initialized()
isPrototypeOf()
logout()
propertyIsEnumerable()
setCredentials()
setPropertyIsEnumerable()
setRemoteCredentials()
toString()
valueOf()

For a complete list of reserved method names, see the Adobe LiveCycle ES ActionScript Reference. Also, do not begin Java method names with the underscore (_) character.

If a remote method name matches a reserved method name, you can use the following ActionScript method with a RemoteObject or WebService component to return an Operation object that represents the method:

public function getOperation(name:String):Operation

For example, if a remote method is called hasOwnProperty(), create an Operation object, as the following example shows:

public var myRemoteObject:RemoteObject = new RemoteObject();
myRemoteObject.destination = "ro-catalog";
public var op:Operation = myRemoteObject.getOperation("hasOwnProperty");

Invoke the remote method by using the Operation.send() method, as the following example shows:

op.send();