24.2. The Seam object

24.2. The `Seam` object

Client-side component interaction is performed with the Seam JavaScript object defined in remote.js. This is used to make asynchronous calls against your component. It is split into two areas of functionality: Seam.Component contains methods for working with components and Seam.Remoting contains methods for executing remote requests. The easiest way to become familiar with this object is to start with a simple example.

24.2.1. A Hello World example

Procedure 24.1. Hello World Example

To show you how the Seam object works, we will first create a new Seam component called helloAction:

@Stateless 
@Name("helloAction") 
public class HelloAction implements HelloLocal { 
    public String sayHello(String name) { 
        return "Hello, " + name; 
    } 
}

We will also need to create a local interface for our new component. In particular, note the @WebRemote annotation, as this is required to make our method accessible via remoting:
```
@Local 
public interface HelloLocal { 
    @WebRemote 
    public String sayHello(String name); 
}
```
This is all the server-side code we require. Next, create a new web page and import the helloAction component:
```
<s:remote include="helloAction"/>
```
Add a button to the page to make this an interactive user experience:
```
<button onclick="javascript:sayHello()">Say Hello</button>
```

You will also need script that performs an action when the button is clicked:

<script type="text/javascript">
function sayHello() {
     var name = prompt("What is your name?");
     Seam.Component.getInstance("helloAction").sayHello(name, sayHelloCallback);
}

function sayHelloCallback(result) {
    alert(result);
}
</script>

Now deploy your application and browse to your page. Click the button, and enter a name when prompted. A message box will display the "Hello" message, confirming the call's success. (You can find the full source code for this Hello World example in Seam's /examples/remoting/helloworld directory.)

You can see from the JavaScript code listing that we have implemented two methods. The first method prompts the user for their name, and makes a remote request. Look at the following line:

Seam.Component.getInstance("helloAction").sayHello(name, sayHelloCallback);

The first section of this line (Seam.Component.getInstance("helloAction")) returns a proxy, or stub, for our helloAction component. The remainder of the line (sayHello(name,sayHelloCallback);) invokes our component methods against the stub.

The whole line invokes the sayHello method of our component, passing in name as a parameter. The second parameter, sayHelloCallback, is not a parameter of our component's sayHello method — it tells the Seam Remoting framework that, once a response to the request is received, the response should be passed to the sayHelloCallback JavaScript method. (This callback parameter is optional; you can leave it out if you are calling a method with a void return type, or if the result of the request is not important.)

When the sayHelloCallback method receives the response to our remote request, it displays an alert message with the result of our method call.