[jboss-cvs] jboss-seam/doc/reference/en/modules ...

[Shane Bryzak]

  User: sbryzak2
  Date: 07/06/21 23:45:58

  Added:       doc/reference/en/modules  gwt.xml
  Log:
  gwt documentation
  
  Revision  Changes    Path
  1.1      date: 2007/06/22 03:45:58;  author: sbryzak2;  state: Exp;jboss-seam/doc/reference/en/modules/gwt.xml
  
  Index: gwt.xml
  ===================================================================
  <chapter id="gwt">
    <title>Seam and the Google Web Toolkit</title>
  
    <para>
      For those that prefer to use the Google Web Toolkit (GWT) to develop dynamic AJAX applications, Seam provides
      an integration layer that allows GWT widgets to interact directly with Seam components.
  
    </para>
    
    <sect1>
      <title>Configuration</title>
      
      <para>
        There is no special configuration required to use GWT in a Seam application, however the Seam resource servlet 
        must be installed.  See <xref linkend="configuration"/> for details.
      </para>
    
    </sect1>
    
    <sect1>
      <title>Preparing your component</title>
      
      <para>
        The first step in preparing a Seam component to be called via GWT, is to create both synchronous and
        asynchronous service interfaces for the methods you wish to call.  Both of these interfaces should extend the
        GWT interface <literal>com.google.gwt.user.client.rpc.RemoteService</literal>:
      </para> 
    
      <programlisting><![CDATA[  public interface MyService extends RemoteService
    {
      public String askIt(String question);      
    }]]></programlisting>
    
      <para>
        The asynchronous interface should be identical, except that it also contains an additional 
        <literal>AsyncCallback</literal> parameter for each of the methods it declares:    
      </para>
      
      <programlisting><![CDATA[  public interface MyServiceAsync extends RemoteService 
    {
      public void askIt(String question, AsyncCallback callback);
    }]]></programlisting>
  
      <para>
        The asynchronous interface, in this example <literal>MyServiceAsync</literal>, will be implemented by GWT and
        should never be implemented directly.
      </para>
      
      <para>
        The next step, is to create a Seam component that implements the synchronous interface:
      </para>
      
      <programlisting><![CDATA[  @Name("org.jboss.seam.example.remoting.gwt.client.MyService")
    public class ServiceImpl implements MyService
    {
      @WebRemote
      public String askIt(String question)
      {
        if (!validate(question)) 
        {
          throw new IllegalStateException("Hey, this shouldn't happen, I checked on the client, " +
                 "but its always good to double check.");
        }
        return "42. Its the real question that you seek now.";
      }
     
      public boolean validate(String q) 
      {
        ValidationUtility util = new ValidationUtility();
        return util.isValid(q);
      }
    }]]></programlisting>
  
      <para>
        The methods that should be made accessible via GWT need to be annotated with the 
        <literal>@WebRemote</literal> annotation, which is required for all web-remoteable methods.
      </para>
    </sect1>
    
    <sect1>
      <title>Hooking up a GWT widget to the Seam component</title>
      
      <para>
        The next step, is to write a method that returns the asynchronous interface to the component.  This method
        can be located inside the widget class, and will be used by the widget to obtain a reference to the
        asynchronous client stub:
      </para>
      
      <programlisting><![CDATA[   private MyServiceAsync getService() 
     {       
        String endpointURL = GWT.getModuleBaseURL() + "seam/resource/gwt";      
        
        MyServiceAsync svc = (MyServiceAsync) GWT.create(MyService.class);
        ((ServiceDefTarget) svc).setServiceEntryPoint(endpointURL);
        return svc;     
     }]]></programlisting>
     
      <para>
         The final step is to write the widget code that invokes the method on the client stub.  The following example
         creates a simple user interface with a label, text input and a button:
      </para>
      
      <programlisting><![CDATA[
  public class AskQuestionWidget extends Composite
  {
     private AbsolutePanel panel = new AbsolutePanel();
     
     public AskQuestionWidget() 
     {      
        Label lbl = new Label("OK, what do you want to know?");
        panel.add(lbl);
        final TextBox box = new TextBox();
        box.setText("What is the meaning of life?");
        panel.add(box);
        Button ok = new Button("Ask");
        ok.addClickListener(new ClickListener() 
        {
           public void onClick(Widget w)
           {
              ValidationUtility valid = new ValidationUtility();
              if (!valid.isValid(box.getText())) 
              {
                 Window.alert("A question has to end with a '?'");
              } 
              else 
              {
                 askServer(box.getText());
              } 
           }
        });
        panel.add(ok);
        
        initWidget(panel);
     }
  
     private void askServer(String text)
     {
        getService().askIt(text, new AsyncCallback() 
        {
           public void onFailure(Throwable t)
           {
              Window.alert(t.getMessage());
           }
  
           public void onSuccess(Object data)
           {
              Window.alert((String) data);
           }         
        });      
     }
     
     ...    
      ]]></programlisting>
      
      
      <para>
        When clicked, the button invokes the <literal>askServer()</literal> method passing the contents of the input text (in this
        example, validation is also performed to ensure that the input is a valid question).  The <literal>askServer()</literal>
        method acquires a reference to the asynchronous client stub (returned by the <literal>getService()</literal> method)
        and invokes the <literal>askIt()</literal> method.  The result (or error message if the call fails) is shown in an alert window.      
      </para>
      
      <mediaobject>
        <imageobject role="fo">
          <imagedata fileref="images/gwt-helloworld.png" align="center"/>
        </imageobject>
        <imageobject role="html">
          <imagedata fileref="../shared/images/gwt-helloworld.png" align="center"/>
        </imageobject>
      </mediaobject>    
      
      
      <para>
        The complete code for this example can be found in the Seam distribution in the <literal>examples/remoting/gwt</literal>
        directory.
      </para>
    </sect1>
    
    <sect1>
      <title>GWT Ant Targets</title>
    
      <para>
      
      </para>
    </sect1>
    
  
  </chapter>