[jboss-cvs] JBossAS SVN: r105609 - projects/docs/enterprise/EAP/trunk/5.x/Seam_Reference_Guide/en-US.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Wed Jun 2 21:04:45 EDT 2010
Author: misty at redhat.com
Date: 2010-06-02 21:04:44 -0400 (Wed, 02 Jun 2010)
New Revision: 105609
Modified:
projects/docs/enterprise/EAP/trunk/5.x/Seam_Reference_Guide/en-US/Remoting.xml
Log:
JBPAPP-4387
Modified: projects/docs/enterprise/EAP/trunk/5.x/Seam_Reference_Guide/en-US/Remoting.xml
===================================================================
--- projects/docs/enterprise/EAP/trunk/5.x/Seam_Reference_Guide/en-US/Remoting.xml 2010-06-03 00:53:03 UTC (rev 105608)
+++ projects/docs/enterprise/EAP/trunk/5.x/Seam_Reference_Guide/en-US/Remoting.xml 2010-06-03 01:04:44 UTC (rev 105609)
@@ -13,7 +13,7 @@
To use remoting, you must first configure your Seam Resource Servlet in your <filename>web.xml</filename> file:
</para>
-<programlisting role="XML"><![CDATA[<servlet>
+<programlisting language="XML" role="XML"><![CDATA[<servlet>
<servlet-name>Seam Resource Servlet</servlet-name>
<servlet-class>
org.jboss.seam.servlet.SeamResourceServlet
@@ -29,7 +29,7 @@
Next, import the necessary JavaScript into your web page. A minimum of two scripts must be imported. The first contains all client-side framework code, which enables remoting functionality:
</para>
-<programlisting role="XHTML"><![CDATA[<script type="text/javascript"
+<programlisting language="XML" role="XML"><![CDATA[<script type="text/javascript"
src="seam/resource/remoting/resource/remote.js">
</script>]]>
</programlisting>
@@ -37,7 +37,7 @@
The second contains the stubs and type definitions for the components you wish to call. This is generated dynamically, based on the local interface of your components, and includes type definitions for all classes that can be used to call the remotable methods of the interface. The script name reflects your component name. For example, if you annotate a stateless session bean with <literal>@Name("customerAction")</literal>, your script tag should look like this:
</para>
-<programlisting role="XHTML"><![CDATA[<script type="text/javascript"
+<programlisting language="XML" role="XML"><![CDATA[<script type="text/javascript"
src="seam/resource/remoting/interface.js?customerAction">
</script>]]>
</programlisting>
@@ -45,7 +45,7 @@
If you want to access more than one component from the same page, include them all as parameters of your script tag:
</para>
-<programlisting role="XHTML"><![CDATA[<script type="text/javascript"
+<programlisting language="XML" role="XML"><![CDATA[<script type="text/javascript"
src="seam/resource/remoting/interface.js?customerAction&accountAction">
</script>]]>
</programlisting>
@@ -53,7 +53,7 @@
You can also use the <literal>s:remote</literal> tag to import the required JavaScript. Separate each component or class name that you want to import with a comma:
</para>
-<programlisting role="XHTML"><![CDATA[<s:remote include="customerAction,accountAction"/>]]>
+<programlisting language="XML" role="XML"><![CDATA[<s:remote include="customerAction,accountAction"/>]]>
</programlisting>
</section>
@@ -68,41 +68,41 @@
To show you how the <literal>Seam</literal> object works, we will first create a new Seam component called <literal>helloAction</literal>:
</para>
-<programlisting role="JAVA"><![CDATA[@Stateless
+<programlisting language="Java" role="JAVA">@Stateless
@Name("helloAction")
public class HelloAction implements HelloLocal {
public String sayHello(String name) {
return "Hello, " + name;
}
-}]]>
+}
</programlisting>
<para>
We will also need to create a local interface for our new component. In particular, note the <literal>@WebRemote</literal> annotation, as this is required to make our method accessible via remoting:
</para>
-<programlisting role="JAVA"><![CDATA[@Local
+<programlisting language="Java" role="JAVA">@Local
public interface HelloLocal {
@WebRemote
public String sayHello(String name);
-}]]>
+}
</programlisting>
<para>
This is all the server-side code we require. Next, create a new web page and import the <literal>helloAction</literal> component:
</para>
-<programlisting role="XHTML"><![CDATA[<s:remote include="helloAction"/>]]>
+<programlisting language="XML" role="XML"><![CDATA[<s:remote include="helloAction"/>]]>
</programlisting>
<para>
Add a button to the page to make this an interactive user experience:
</para>
-<programlisting role="XHTML"><![CDATA[<button onclick="javascript:sayHello()">Say Hello</button>]]>
+<programlisting language="XML" role="XML"><![CDATA[<button onclick="javascript:sayHello()">Say Hello</button>]]>
</programlisting>
<para>
You will also need script that performs an action when the button is clicked:
</para>
-<programlisting role="XHTML"><![CDATA[<script type="text/javascript">
+<programlisting language="XML" role="XML"><![CDATA[<script type="text/javascript">
//<<![CDATA[ function sayHello() {
var name = prompt("What is your name?");
Seam.Component.getInstance("helloAction").sayHello(name, sayHelloCallback);
@@ -121,7 +121,7 @@
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:
</para>
-<programlisting role="XHTML">
+<programlisting language="XML" role="XML">
Seam.Component.getInstance("helloAction").sayHello(name, sayHelloCallback);
</programlisting>
<para>
@@ -146,7 +146,7 @@
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:
</para>
-<programlisting role="JAVA">
+<programlisting language="Java" role="JAVA">
@Name("customer")
@Entity
public class Customer implements Serializable
@@ -184,14 +184,14 @@
To create a client-side Customer you would write the following code:
</para>
-<programlisting role="XHTML">
+<programlisting language="XML" role="XML">
var customer = Seam.Component.newInstance("customer");
</programlisting>
<para>
From here, you can set the fields of the customer object.
</para>
-<programlisting role="XHTML">
+<programlisting language="XML" role="XML">
customer.setFirstName("John"); // Or you can set the fields directly
// customer.lastName = "Smith";
</programlisting>
@@ -206,7 +206,7 @@
To continue the previous example, if we have created a new <literal>customer</literal> and we want to save it, we pass it to the <literal>saveCustomer()</literal> method of our <literal>customerAction</literal> component:
</para>
-<programlisting role="XHTML">
+<programlisting language="XML" role="XML">
Seam.Component.getInstance("customerAction").saveCustomer( customer);
</programlisting>
</section>
@@ -217,7 +217,7 @@
Passing an object into this method returns the component name, if it is a component, or <literal>null</literal> if it is not.
</para>
-<programlisting role="XHTML">
+<programlisting language="XML" role="XML">
if (Seam.Component.getComponentName(instance) == "customer")
alert("Customer");
else if (Seam.Component.getComponentName(instance) == "staff")
@@ -238,7 +238,7 @@
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 <literal>createType()</literal> method to create an instance of your type. Pass in the fully-qualified Java class name as a parameter:
</para>
-<programlisting role="XHTML">
+<programlisting language="XML" role="XML">
var widget = Seam.Remoting.createType("com.acme.widgets.MyWidget");
</programlisting>
</section>
@@ -260,7 +260,7 @@
Seam Remoting also supports EL expression evaluation, which is another convenient method of retrieving data from the server. The <literal>Seam.Remoting.eval()</literal> function lets the EL expression be remotely evaluated on the server, and returns the resulting value to a client-side callback method. This function accepts two parameters: the EL expression to evaluate, and the callback method to invoke with the expression value. For example:
</para>
-<programlisting role="XHTML"><![CDATA[function customersCallback(customers) {
+<programlisting language="XML" role="XML"><![CDATA[function customersCallback(customers) {
for (var i = 0; i < customers.length; i++) {
alert("Got customer: " + customers[i].getName());
}
@@ -273,7 +273,7 @@
Here, Seam evaluates the <literal>#{customers}</literal> expression, and the value of the expression (in this case, a list of <literal>Customer</literal> objects) is returned to the <literal>customersCallback()</literal> method. Remember, objects returned this way must have their types imported with <literal>s:remote</literal> for you to work with them in JavaScript. To work with a list of <literal>customer</literal> objects, you must be able to import the <literal>customer</literal> type:
</para>
-<programlisting role="XHTML"><![CDATA[<s:remote include="customer"/>]]>
+<programlisting language="XML" role="XML"><![CDATA[<s:remote include="customer"/>]]>
</programlisting>
</section>
@@ -283,12 +283,12 @@
In the previous configuration section, the stub for our component is imported into our page with either <literal>seam/resource/remoting/interface.js</literal>, or with the <literal>s:remote</literal> tag:
</para>
-<programlisting role="XHTML"><![CDATA[<script type="text/javascript"
+<programlisting language="XML" role="XML"><![CDATA[<script type="text/javascript"
src="seam/resource/remoting/interface.js?customerAction">
</script> ]]>
</programlisting>
-<programlisting role="XHTML"><![CDATA[<s:remote include="customerAction"/>]]>
+<programlisting language="XML" role="XML"><![CDATA[<s:remote include="customerAction"/>]]>
</programlisting>
<para>
Including this script generates the interface definitions for our component, plus any other components or types required to execute the methods of our component, and makes them available for the remoting framework's use.
@@ -322,7 +322,7 @@
Under some circumstances, you may need to make a remote call within the scope of the current view's conversation. To do so, you must explicitly set the conversation ID to that of the view before making the remote call. The following JavaScript will set the conversation ID being used for remote calls to the current view's conversation ID:
</para>
-<programlisting role="XHTML"><![CDATA[Seam.Remoting.getContext().setConversationId( #{conversation.id} );]]>
+<programlisting language="XML" role="XML"><![CDATA[Seam.Remoting.getContext().setConversationId( #{conversation.id} );]]>
</programlisting>
</section>
@@ -383,7 +383,7 @@
Only objects created by either of these two methods should be used as parameter values, where the parameter is not one of the preexisting valid types. You may encounter component methods where the exact parameter type cannot be determined, such as:
</para>
-<programlisting role="JAVA">
+<programlisting language="Java" role="JAVA">
@Name("myAction")
public class MyAction implements MyActionLocal {
public void doSomethingWithObject(Object obj) {
@@ -395,7 +395,7 @@
In this case, the interface for <literal>myAction</literal> will not include <literal>myWidget</literal>, because it is not directly referenced by any of its methods. Therefore, you cannot pass in an instance of your <literal>myWidget</literal> component unless you import it explicitly:
</para>
-<programlisting role="XHTML"><![CDATA[<s:remote include="myAction,myWidget"/>]]>
+<programlisting language="XML" role="XML"><![CDATA[<s:remote include="myAction,myWidget"/>]]>
</programlisting>
<para>
This allows a <literal>myWidget</literal> object to be created with <literal>Seam.Component.newInstance("myWidget")</literal>, which can then be passed to <literal>myAction.doSomethingWithObject()</literal>.
@@ -415,7 +415,7 @@
On the client side, enums are treated similarly to Strings. When setting the value for an enum parameter, use the String representation of the enum. Take the following component as an example:
</para>
-<programlisting role="JAVA">
+<programlisting language="Java" role="JAVA">
@Name("paintAction")
public class paintAction implements paintLocal {
public enum Color {red, green, blue, yellow, orange, purple};
@@ -428,7 +428,7 @@
To call the <literal>paint()</literal> method with the color <literal>red</literal>, pass the parameter value as a String literal:
</para>
-<programlisting role="XHTML">
+<programlisting language="XML" role="XML">
Seam.Component.getInstance("paintAction").paint("red");
</programlisting>
<para>
@@ -451,7 +451,7 @@
The Seam Remoting framework provides simple map support where no native support is available in JavaScript. To create a map that can be used as a parameter to a remote call, create a new <literal>Seam.Remoting.Map</literal> object:
</para>
-<programlisting role="XHTML">var map = new Seam.Remoting.Map();
+<programlisting language="XML" role="XML">var map = new Seam.Remoting.Map();
</programlisting>
<para>
This JavaScript implementation provides basic methods for working with Maps: <literal>size()</literal>, <literal>isEmpty()</literal>, <literal>keySet()</literal>, <literal>values()</literal>, <literal>get(key)</literal>, <literal>put(key, value)</literal>, <literal>remove(key)</literal> and <literal>contains(key)</literal>. Each of these methods is equivalent to the Java method of the same name. Where the method returns a collection, as in <literal>keySet()</literal> and <literal>values()</literal>, a JavaScript array object will be returned that contains the key or value objects (respectively).
@@ -468,14 +468,14 @@
To help you track down bugs, you can enable a debug mode, which displays the contents of all packets sent between client and server in a pop-up window. To enable debug mode, either execute the <literal>setDebug()</literal> method in JavaScript, like so:
</para>
-<programlisting role="XHTML">
+<programlisting languge="Java" role="JAVA">
Seam.Remoting.setDebug(true);
</programlisting>
<para>
Or configure it in <filename>components.xml</filename>:
</para>
-<programlisting role="XML"><![CDATA[<remoting:remoting debug="true"/>]]>
+<programlisting language="XML" role="XML"><![CDATA[<remoting:remoting debug="true"/>]]>
</programlisting>
<para>
To turn off debug mode, call <literal>setDebug(false)</literal>. If you want to write your own messages to the debug log, call <literal>Seam.Remoting.log(message)</literal>.
@@ -488,24 +488,24 @@
When invoking a remote component method, you can specify an exception handler to process the response in the event of an exception during component invocation. To specify an exception handler function, include a reference to it after the callback parameter in your JavaScript:
</para>
-<programlisting><![CDATA[var callback = function(result) {
+<programlisting language="Java" role="JAVA">var callback = function(result) {
alert(result);
};
var exceptionHandler = function(ex) {
alert("An exception occurred: " + ex.getMessage());
};
Seam.Component.getInstance("helloAction")
- .sayHello(name, callback, exceptionHandler);]]>
+ .sayHello(name, callback, exceptionHandler);
</programlisting>
<para>
If you do not have a callback handler defined, you must specify <literal>null</literal> in its place:
</para>
-<programlisting><![CDATA[var exceptionHandler = function(ex) {
+<programlisting language="Java" role="JAVA">var exceptionHandler = function(ex) {
alert("An exception occurred: " + ex.getMessage());
};
Seam.Component.getInstance("helloAction")
- .sayHello(name, null, exceptionHandler);]]>
+ .sayHello(name, null, exceptionHandler);
</programlisting>
<para>
The exception object that is passed to the exception handler exposes one method, <literal>getMessage()</literal>, which returns the exception message belonging to the exception thrown by the <literal>@WebRemote</literal> method.
@@ -523,7 +523,7 @@
To change the message from the default "Please Wait...", set the value of <literal>Seam.Remoting.loadingMessage</literal>:
</para>
-<programlisting role="XHTML">
+<programlisting language="Java" role="JAVA">
Seam.Remoting.loadingMessage = "Loading...";
</programlisting>
</section>
@@ -534,7 +534,7 @@
To completely suppress the display of the loading message, override the implementation of <literal>displayLoadingMessage()</literal> and <literal>hideLoadingMessage()</literal> with actionless functions:
</para>
-<programlisting role="XHTML">
+<programlisting language="Java" role="JAVA">
// don't display the loading indicator
Seam.Remoting.displayLoadingMessage = function() {};
Seam.Remoting.hideLoadingMessage = function() {};
@@ -547,7 +547,7 @@
It is also possible to override the loading indicator to display an animated icon, or anything else that you want. To do so, override the <literal>displayLoadingMessage()</literal> and <literal>hideLoadingMessage()</literal> messages with your own implementations:
</para>
-<programlisting role="XHTML">
+<programlisting language="Java" role="JAVA">
Seam.Remoting.displayLoadingMessage = function() {
// Write code here to display the indicator
};
@@ -571,15 +571,15 @@
The examples that follow are all based on this <literal>Widget</literal> class:
</para>
-<programlisting role="JAVA"><![CDATA[@Name("widget")
+<programlisting language="Java" role="JAVA">@Name("widget")
public class Widget {
private String value;
private String secret;
private Widget child;
- private Map<String,Widget> widgetMap;
- private List<Widget> widgetList;
+ private Map<String,Widget> widgetMap;
+ private List<Widget> widgetList;
- // getters and setters for all fields]]>
+ // getters and setters for all fields
</programlisting>
<section>
<title>Constraining normal fields</title>
@@ -587,7 +587,7 @@
If your remote method returns an instance of <literal>Widget</literal>, but you do not want to expose the <literal>secret</literal> field because it contains sensitive information, you would constrain it like so:
</para>
-<programlisting role="JAVA">
+<programlisting language="Java" role="JAVA">
@WebRemote(exclude = {"secret"})
public Widget getWidget();
</programlisting>
@@ -598,7 +598,7 @@
Now, note that the returned <literal>Widget</literal> value has a field <literal>child</literal> that is also a <literal>Widget</literal>. If we want to hide the <literal>child</literal>'s <literal>secret</literal> value, rather than the field itself, we can use dot notation to specify this field's path within the result object's graph:
</para>
-<programlisting role="JAVA">
+<programlisting language="Java" role="JAVA">
@WebRemote(exclude = {"child.secret"})
public Widget getWidget();
</programlisting>
@@ -610,7 +610,7 @@
Objects within an object graph can also exist in a <literal>Map</literal> or a Collection (that is, a <literal>List</literal>, a <literal>Set</literal>, an <literal>Array</literal>, etc.). Collections are treated like any other field — for example, if our <literal>Widget</literal> contained a list of other <literal>Widget</literal>s in its <literal>widgetList</literal> field, we would constrain the <literal>secret</literal> field of the <literal>Widget</literal>s in this list with the following notation:
</para>
-<programlisting role="JAVA">
+<programlisting language="Java" role="JAVA">
@WebRemote(exclude = {"widgetList.secret"})
public Widget getWidget();
</programlisting>
@@ -618,7 +618,7 @@
To constrain a <literal>Map</literal>'s key or value, the notation is slightly different. Appending <literal>[key]</literal> after the <literal>Map</literal>'s field name constrains the <literal>Map</literal>'s key object values, while <literal>[value]</literal> constrains the value object values. The following example demonstrates how the values of the <literal>widgetMap</literal> field have their <literal>secret</literal> field constrained:
</para>
-<programlisting role="JAVA">
+<programlisting language="Java" role="JAVA">
@WebRemote(exclude = {"widgetMap[value].secret"})
public Widget getWidget();
</programlisting>
@@ -630,7 +630,7 @@
You can use square brackets to constrain the fields of an object type regardless of its location in the object graph. If the object is a Seam component, use the name of the component; if not, use the fully-qualified class name, like so:
</para>
-<programlisting role="JAVA">
+<programlisting language="Java" role="JAVA">
@WebRemote(exclude = {"[widget].secret"})
public Widget getWidget();
</programlisting>
@@ -642,7 +642,7 @@
Constraints can also be combined to filter objects from multiple paths within the object graph:
</para>
-<programlisting role="JAVA">
+<programlisting language="Java" role="JAVA">
@WebRemote(exclude = {"widgetList.secret", "widgetMap[value].secret"})
public Widget getWidget();
</programlisting>
@@ -656,11 +656,11 @@
By default, no transaction is active during a remoting request. If you wish to update the database during a remoting request, you must annotate the <literal>@WebRemote</literal> method with <literal>@Transactional</literal>, like so:
</para>
-<programlisting><![CDATA[@WebRemote
+<programlisting language="Java" role="JAVA">@WebRemote
@Transactional(TransactionPropagationType.REQUIRED)
public void updateOrder(Order order) {
entityManager.merge(order);
-}]]>
+}
</programlisting>
</section>
@@ -675,7 +675,7 @@
Before you can subscribe to a JMS topic, you must first configure a list of the topics that Seam Remoting can subscribe to. List the topics under <literal>org.jboss.seam.remoting.messaging.subscriptionRegistry. allowedTopics</literal> in <filename>seam.properties</filename>, <filename>web.xml</filename> or <filename>components.xml</filename>:
</para>
-<programlisting role="XML"><![CDATA[<remoting:remoting poll-timeout="5" poll-interval="1"/>]]>
+<programlisting language="XML" role="XML"><![CDATA[<remoting:remoting poll-timeout="5" poll-interval="1"/>]]>
</programlisting>
</section>
@@ -685,7 +685,7 @@
The following example demonstrates how to subscribe to a JMS Topic:
</para>
-<programlisting role="XHTML">
+<programlisting language="XML" role="XML">
function subscriptionCallback(message) {
if (message instanceof Seam.Remoting.TextMessage)
alert("Received message: " + message.getText());
@@ -706,7 +706,7 @@
To unsubscribe from a topic, call <literal>Seam.Remoting.unsubscribe()</literal> and pass in the topic name:
</para>
-<programlisting role="XHTML">
+<programlisting language="XML" role="XML">
Seam.Remoting.unsubscribe("topicName");
</programlisting>
</section>
@@ -732,13 +732,13 @@
In <filename>components.xml</filename>:
</para>
-<programlisting role="XML"><![CDATA[<remoting:remoting poll-timeout="5" poll-interval="1"/>]]>
+<programlisting language="XML" role="XML"><![CDATA[<remoting:remoting poll-timeout="5" poll-interval="1"/>]]>
</programlisting>
<para>
With JavaScript:
</para>
-<programlisting role="XHTML">
+<programlisting language="XML" role="XML">
// Only wait 1 second between receiving a poll response and sending
// the next poll request.
Seam.Remoting.pollInterval = 1;
More information about the jboss-cvs-commits
mailing list