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 {
	@WebRemote
	public String sayHello(String name) {
		return "Hello, " + name;
	}
}
```
Take special note of the @WebRemote annotation, as it's required to make our method accessible via remoting:
That's all the server-side code we need to write.
Note
If you are performing a persistence operation in the method marked @WebRemote you will also need to add a @Transactional annotation to the method. Otherwise, your method would execute outside of a transaction without this extra hint.That's because unlike a JSF request, Seam does not wrap the remoting request in a transaction automatically.
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">
//<![CDATA[
	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.

⁠24.2.2. Seam.Component

The Seam.Component JavaScript object provides a number of client-side methods for working with your Seam components. The two main methods, newInstance() and getInstance() are documented more thoroughly in the sections following. The main difference between them is that newInstance() will always create a new instance of a component type, and getInstance() will return a singleton instance.

⁠24.2.2.1. Seam.Component.newInstance()

Use this method to create a new instance of an entity or JavaBean component. The object returned will have the same getter/setter methods as its server-side counterpart. You can also access its fields directly. For example:

@Name("customer")
@Entity
public class Customer implements Serializable
{
	private Integer customerId;
	private String firstName;
	private String lastName;
			
	@Column public Integer getCustomerId() { 
		return customerId; 
	}
			
	public void setCustomerId(Integer customerId} { 
		this.customerId = customerId; 
	}
			
	@Column public String getFirstName() { 
		return firstName; 
	}
			
	public void setFirstName(String firstName) {
		this.firstName = firstName; 
	}
			
	@Column public String getLastName() {
		return lastName;
	}
			
	public void setLastName(String lastName) {
		this.lastName = lastName;
	}
}

To create a client-side Customer you would write the following code:

var customer = Seam.Component.newInstance("customer");

From here, you can set the fields of the customer object.

customer.setFirstName("John");
// Or you can set the fields directly
customer.lastName = "Smith";

⁠24.2.2.2. Seam.Component.getInstance()

The getInstance() method is used to refer to a Seam session bean component stub, which can then be used to remotely execute methods against your component. This method returns a singleton for the specified component, so calling it twice in a row with the same component name will return the same instance of the component.

To continue the previous example, if we have created a new customer and we want to save it, we pass it to the saveCustomer() method of our customerAction component:

Seam.Component.getInstance("customerAction").saveCustomer(customer);

⁠24.2.2.3. Seam.Component.getComponentName()

Passing an object into this method returns the component name, if it is a component, or null if it is not.

if (Seam.Component.getComponentName(instance) == "customer")
	alert("Customer");
	
	else if (Seam.Component.getComponentName(instance) == "staff")
	
	alert("Staff member");

⁠24.2.3. Seam.Remoting

Most of the client side functionality for Seam Remoting is held within the Seam.Remoting object. You should not need to directly call many of its methods, but there are several that are useful:

⁠24.2.3.1. Seam.Remoting.createType()

If your application contains or uses JavaBean classes that are not Seam components, you may need to create these types on the client side to pass as parameters into your component method. Use the createType() method to create an instance of your type. Pass in the fully-qualified Java class name as a parameter:

var widget = Seam.Remoting.createType("com.acme.widgets.MyWidget");

⁠24.2.3.2. Seam.Remoting.getTypeName()

This method is the non-component equivalent of Seam.Component.getComponentName(). It returns the name of the type for an object instance, or null if the type is not known. The name is the fully-qualified name of the type's Java class.