DWR – Easy Ajax for Java

1. DWR – Easy Ajax for Java Ivanka Todorova April 4, 2007

2. Acknowledgements • These slides are created from contents from DWR web site http://getahead.org/dwr • Many slides are based on: • Sang Shin. Introduction to DWR (Direct Web Remoting). Retrieved April 1, 2007 on the World Wide Web: http://www.javapassion.com/ajax/DWR.pdf

3. Topics • What is DWR? • Steps for building DWR-based AJAX application • Registering callback functions • Converters • Creators • Utility functions • Additional Resources with Coding Examples of DWR Applications

4. What is DWR?

5. What is DWR? • Consists of a server-side Java libraries, a DWR servlet, and JavaScript libraries that allow you to write Ajax web applications • Hides low-level XMLHttpRequest Handling • Specifically designed with Java technology in mind • “Easy Ajax for Java” • Allows JavaScript code in a browser to use Java functions running on a web server as if they were in the browser • That’s why it is called “Direct remoting”

6. Why DWR? • Without DWR, you would have to create many Web application endpoints (servlets) that need to be addressable via URIs • If you have several methods in a class on the server that you want to invoke from the browser • Each of these methods need to be addressable via URI • You would have to map parameters and return values to HTML input form parameters and responses yourself • DWR comes with some JavaScript utility functions

7. 1. How Does DWR Work? • DWR dynamically generates a matching client-side JavaScript class from a backend Java class • Allows you to write JavaScript code that looks like conventional RPC/RMI code • The generated JavaScript class handles remoting details between the browser and the backend server • Handles asynchronous communication via XMLHttpRequest by invoking the callback function in the JavaScript • You provide the callback function as additional parameter • DWR converts all the parameters and return values between client-side JavaScript and backend Java.

8. 2. How DWR Works DWR dynamically generates an AjaxService class in Javascript to match some server-side code. This is called by the eventHandler. DWR then handles all the remoting details, including converting all the parameters and return values between Javascript and Java. It then executes the supplied callback function (populateList) which uses a DWR utility function to alter the web page.

9. DWR Consists of Two Main Parts • A Java Servlet running on the server that processes requests and sends responses back to the browser. • uk.ltd.getahead.dwr.DWRServlet • This servlet delegates the call to the backend class you specify in the dwr.xml configuration file • JavaScript running in the browser that sends requests and can dynamically update the webpage. • DWR handles XMLHttpRequest handling

10. Steps for Building DWR-based AJAX Application

11. Steps • Download the dwr.jar file and place it in the WEB-INF/lib directory of your webapp • dwr.jar contains DWR runtime code including the DWR servlet • Edit web.xml in the WEB-INF directory • add servlet and servlet mapping information • Create dwr.xml file in the WEB-INF directory • You specify classes and methods DWR can create and remote for use by client-side JavaScript code

12. Step #2 Edit web.xml in the WEB-INF directory <servlet> <servlet-name>dwr-invoker</servlet-name> <display-name>DWR Servlet</display-name> <servlet-class>uk.ltd.getahead.dwr.DWRServlet</servlet-class> <init-param> <param-name>debug</param-name><param-value>true</param-value> </init-param> </servlet> <servlet-mapping> <servlet-name>dwr-invoker</servlet-name> <url-pattern>/dwr/*</url-pattern> </servlet-mapping>

13. Step#3 Create dwr.xml file in the WEB-INF directory • The example below creates a JavaScript class “JDate” matching the Java class “java.util.Date” <!DOCTYPE dwr PUBLIC "-//GetAhead Limited//DTD Direct Web Remoting 1.0//EN" "http://www.getahead.ltd.uk/dwr/dwr10.dtd"> <dwr> <allow> <create creator="new" javascript="JDate"> <param name="class" value="java.util.Date"/> </create> </allow> </dwr>

14. Test and Deploy the Application • Go to the following URL: http://localhost:8088/[YOUR-WEBAPP]/dwr/ • You should see a page showing you the classes that you've selected and an index of all the methods known to DWR. • NETBEANS IDE 5.5 TROUBLESHOOTING TIP • You may choose a different port number • If you run your code multiple times and get the message “Server Port Already in Use” in go to Tools, Server Manager and change the port number.

15. Registering Callback Functions for AJAX-based Asynchronous Invocation

16. How DWR Handles Asynchronous AJAX Call • Calling JavaScript function at the client needs to be done asynchronously while calling a Java method (at the server) is synchronous • DWR has to handle this mismatch • DWR provides a scheme for registering a callback function at the client • This callback function is called when the data is returned from the server – this is AJAX behavior • You pass the callback function as an additional parameter

17. 1. How the Callback Function is Registered • Suppose we have a Java method that looks like this: //Server side Java code public class MyRemoteJavaClass{ public String getData(int index){…} } • We can use this from JavaScript as follows //Callback function to be called function handleGetData(str) { alert(str); }

18. 2. How the Callback Function is Registered • The callback function is passed as an additional parameter MyRemoteJavaScriptClass.getData(42, handleGetData); • Alternatively you can use the all-in-one-line version Remote.getData(42, function(str) { alert(str); }); • Or we can use a call meta-data object that specifies the callback function Remote.getData(42, { callback: function(str) { alert(str); } }); • In addition to the callback metadata you can also specify a timeout and an error handler Remote.getData(42, { callback:function(str) { alert(str); }, timeout:5000, errorHandler:function(message) { alert("Oops: " + message); } });

19. Finding the Callback Method • If there is a function first or last then this is the callback function • If the first parameter is null we assume that there is no callback function. We check to see that the last param is not null and give a warning if it is. • If the last param is null, then there is no callback function.

20. 1. Creating JavaScript objects to Match Java objects • Suppose you have an exposed Java method like this: public class Remote { public void setPerson(Person p) { this.person = p; } } • And Person looks like this: public Person { private String name; private int age; private Date[] appointments; // getters and setters ... }

21. 2. Creating JavaScript objects to Match Java objects • Then you can call this from JavaScript like this: var p = { name:"Fred Bloggs", age:42, appointments:[ new Date(), new Date("1 Jan 2008") ] }; Remote.setPerson(p); • Any fields missing from the JavaScript representation will be left unset in the Java version.

22. Converters

23. Types of Converters • A converter converts data between the client and the server • Types of converters provided by DWR • Basic Converters • Bean and Object Converters • Enum Converters • Collection Converter • DOM Objects • Servlet Objects (HttpServletRequest, HttpSession, etc.) • While you can create your own converters this is rarely needed

24. Handle Boolean, byte, short, int, long, float, double, char, java.lang.Boolean, java.lang. byte, java.lang.Short, java.lang.Integer, java.lang.Long, java.lang.Float, java.lang.Double, java.lang.Character, java.math.BigInteger, java.math.BigDecimal and java.lang.String No need to have a <convert> element in the <allow>section in dwr.xml to use them. They are enabled by default A Date Converter converts data between a JavaScript date and a java.util.Date, java.sql.Date, java.sql.Times, or, java.sql. Timestamp Basic Converters

25. 1. Bean and Object Converters • The Bean converter converts Plain Old Java Objects (POJOs) into JavaScript Associative arrays and back again. • The Object converter is similar except that it works on object members directly rather than through getters and setters. • You can enable the bean converter for a single class using the following:<convert converter="bean" match="your.full.package.BeanName"/> • To allow conversion of any class in the given package, or sub package: <convert converter="bean" match="your.full.package.*"/>

26. 2. Bean and Object Converters • DWR will convert Javascript objects (aka maps, aka associative arrays) into Java beans or Java objects. public class Remoted { public void setPerson(Person p) { // ... } } public class Person { public void setName(String name) { ... } public void setAge(int age) { ... } // ... } • If Remoted was configured as a Creator, and Person is convertible using the Bean Converter, then you can call the Java code as follows: var p = { name:"Fred", age:21 }; Remoted.setPerson(p);

27. 3. Bean and Object Converters • Restricting Property Conversions Just as you have exclude and include for creators to instruct DWR to exclude methods, there is a similar system for Bean Converters : <convert converter="bean" match="com.example.Fred"> <param name="exclude" value="property1, property2"/> </convert> • This will ensure that DWR does not call fred.getProperty1() and fred.getProperty2. • Alternatively if you prefer to white-list rather than black-list you can do the following: <convert converter="bean" match="com.example.Fred"> <param name="include" value="property1, property2"/> </convert> • Good security design commonly involves white-listing rather than black-listing.

28. Collection Converters • The final two default converters are for maps and collections: <convert converter="collection" match="java.util.Collection"/> and <convert converter="map" match="java.util.Map"/> • Generally speaking these converters will be able to recursively convert their contents. • The two converters above can convert from any collection to something meaningful in JavaScript, however there is no way to know what sort of Collection to convert to going the other way. • Since we can't work it out automatically we may need to use the special signatures syntax in the dwr.xml file to allow us to hint types to the conversion process.

29. 1. Enum Converters • Converts Java5 Enums into JavaScript strings and back again. Not enabled by default. • You can enable the Enum Converter for a single class using the following: <convert converter="enum" match="your.full.package.EnumName"/> • Setting up JavaScript variables public class Remoted { public void setStatus(Status p) { // ... } } enum Status { PASS, FAIL, }

30. 2. Enum Converter • If Remoted was configured as a Creator, and Status is convertible using the EnumConverter, then you can call the Java code from JavaScript as follows: Remoted.setStatus("PASS"); • If no match is found in the given enum, then an exception will be thrown.

31. DOM Objects • DWR automatically converts DOM trees from DOM, DOM4J, JDOM and XOM. • You simply return a Document, Element or Node from any of the above and DWR will automatically convert it into a browser DOM object.

32. 1. Servlet Objects • There are only 2 Java classes that you commonly need to depend on within DWR as a user - WebContext and WebContextFactory. • These classes give you access to the standard HTTP servlet objects: HttpServletRequest , HttpServletResponse, HttpSession, ServletContext, and ServletConfig • It is important that you treat the HTTP request and response as read only. Any attempt to change the HTTP body will cause DWR errors.

33. 2. Servlet Objects • The alternative method is to access the HTTP servlet objects without writing code that depends on DWR – just have the needed parameter declared on your code. • For example if you have remoted a class like this: public class Remote { public void method (int param, ServletContext cx, String s) { ... } } Then you will be able to access it from Javascript just as though the ServletContext parameter was not there: Remote.method(42, "test", callback); • Make sure you are not using the callback function as first parameter, instead use the callback as last parameter.

34. Creators

35. 1. Creators • The create element in your dwr.xml file has the following structure. <allow> <create creator="..." javascript="..." scope="..."> <param name="..." value="..."/> <auth method="..." role="..."/> <exclude method="..."/> <include method="..."/> </create> ... </allow> • Most of these elements are optional. All you really need is to specify a creator and a JavaScript name. The creator attribute is required – it specifies which creator will be used. • The javascript attribute gives your newly created object a name in the browser.

36. 2. Creators • The scope attribute is optional. It defaults to “page”. The other options are “application”, “session”, and “request”. • The param attribute is used by the various creators for specific bits of configuration. For example the 'new' creator needs to be told what type of object to call 'new' on. • The include and exclude elements allow a creator to restrict access to class methods. A Creator should specify EITHER a list of include elements (which implies that the default policy is denial) OR a list of exclude elements (which implies that the default policy is to allow access). • For example to deny access to all methods in some class except for the setHourlyPay() method you should put the following into your dwr.xml <create creator="new" javascript="Fred"> <param name="class" value="com.example.Fred"/> <auth method="setHourlyPay" role="admin"/> </create>

37. 3. Creators • The new creator is declared by default by DWR as follows: <creator id="new" class="uk.ltd.getahead.dwr.create.NewCreator"/>. It creates an instance of a class using the default constructor. • You allow DWR to use the new creator to create and remote your beans as follows: <allow> <create creator="new" javascript=“Date"> <param name="class" value="java.util.Date"/> </create> ... </allow> • This remotes java.util.Date to Javascript and gives it the name Date so in Javascript when you call Date.toString(reply) then a new java.util.Date will be constructed using the default constructor, then the toString() method will be called, and the data returned to the javascript reply function (in this case the current date in string form).

38. Creators and Converters Summary • Creators create objects that live on the server and have their methods remoted • Converters convert parameters and return types • Created objects do things while converted objects carry data var r=Remote.method (param, callback) creator converter

39. Utility Functions

40. 1. Utility Functions • The util.js contains utility functions to help you update your web pages with JavaScript data • You can even use it outside of DWR because it does not depend on DWR to function • Some of the available utility functions are: • $(id) • getValue, getValues, setValue, setValues • addRows and removeAllRows

41. 2. Utility Functions • $(id) is the same as • Document.getElementById(id) in DOM API • DWRUtil.getValue(id) get the value(s) out of the HTML elements • DWRUtil.setValue(id, value) finds the element with the id in the first parameter and alters its contents to the second parameter

42. 1. Tutorials and Articles about DWR • DWR Hands-on Lab by Sang Shin, Sun Microsystems. Retrieved April 3, 2007 from the World Wide Web: http://www.javapassion.com/handsonlabs/ajaxdwrintro/ • Contains full code for four applications: Chat, Populating Selection List, Form Editing, and Table Editing. • AJAX made simple with DWR by Cloves Carneiro Jr., JavaWorld.com, 06/20/05. Retrieved April 3, 2007 from the World Wide Web: http://www.javaworld.com/javaworld/jw-06-2005/jw-0620-dwr.html • The example application used in this article simulates an apartment rental search engine for the city of Toronto. The user can select a set of search criteria before performing the search.

43. 2. Tutorials and Articles about DWR • Ajax for Java developers: Ajax with Direct Web Remoting by Philip McCarthy. Retrieved April 3, 2007 from the World Wide Web: http://www-128.ibm.com/developerworks/java/library/j-ajax3/ • Includes implementation of a shopping cart • Extensive list of tutorials and articles about DWR. Retrieved April 3, 2007 from the World Wide Web: http://getahead.org/dwr/elsewhere Definitely worth visiting!