The Flash to server communication is done using WDDX.
What is WDDX? Where does it come from?
This is a free, open XML-based technology which has a Flash and a Java implementation. The initial development was done by people connected with Macromedia, but the product is unsupported. See http://www.openwddx.org/.
It is not widely used as there are better technologies available from Macromedia for Flash to Java communication. However these other technologies must be purchased from Macromedia so they aren't suitable for LAMS.
We have made some modifications to correct some problems. If WDDX ever takes off again, then we are happy to share our modifications.
Sending From Flash to Java.
Flash sends the WDDX packet in the POST of a HTTP call. It is not in the standard parameter=value format, the whole body is the WDDX packet.
For this reason, the server code that receives the packet should be an ordinary servlet and not a Struts action. The packet is read using request.getReader(), and in a Struts action, the body appears to be already consumed (presumably by Struts).
To make it easier, a servlet has been written that takes care of reading the WDDX packet, and returning the error packet if an exception occurs during your processing. Please use this servlet - it will make the Java side consistent and so make things easier for the Flash developer(s). See org.lamsfoundation.lams.web.servlet.AbstractStoreWDDXPacketServlet for more details.
Sending From Java to Flash.
A packet from the server to Flash should be sent as the HTTP output stream. Just the packet should be sent. The packet should not be wrapped up in an HTML page.
All packets that are sent from the server to Flash should be a wddx serialized version of the org.lamsfoundation.lams.util.wddx.FlashMessage object.
When working with WDDX, please use the utility classes in the org.lamsfoundation.lams.util.wddx package (in lams.jar).
WDDX works well with Hashtables and ArrayLists. If you require a collection that will go through the WDDX serialiser then use these two classes. Other collection types cause problems, usually due to nulls. If you are sending a series of fields, then either serialise a DTO or a hashtable. If you are sending a set of the same objects use ArrayList.
WDDX does not cope with null well. A WDDX packet from Flash must not contain <NULL/>, or the WDDX processor will throw an exception. The WDDX serialiser will trigger an exception when trying to process a Java object containing nulls.
So the following conventions are used in our code:
- If the server is sending a value to the client, then any fields with null values should be omitted from the objects.
- If the client is sending a value to the server and a field is omitted from the packet then the server is to assume that the field value has not changed (ie don't update the database).
- If the client is sending a value to the server and a field's value is one of the special null values (see below) then the server should consider the field value as null.
Special null values (from org.lamsfoundation.lams.util.wddx.WDDXTAGS):
- Long NUMERIC_NULL_VALUE_LONG = new Long(-111111);
- String STRING_NULL_VALUE = "string_null_value";
- Integer NUMERIC_NULL_VALUE_INTEGER = new Integer(-111111);
- Date DATE_NULL_VALUE = new Date(0);
- Boolean BOOLEAN_NULL_VALUE = new Boolean("false");
Testing utilities - Upload a packet using wddxPost.jsp, Parse a packet using dumpWDDX
To make it easier to test (without having to get Flash working), there is now a JSP page that will let you upload a packed in a similar manner to Flash.
As this utility is only for developers, the page is initially disabled when LAMS is installed. To enable the page, go to the struts-config.xml file in lams-central.war and uncomment the entries for WDDXPostActionForm and WDDXPostAction and then restart JBOSS. The uploading/parsing utilities should then work.
This is a secure page, so if you were not logged you will be taken to the login page. Log in as normal and then try this url again.
In the Form Action field, put in the complete URL of the servlet that should be called. e.g. http://localhost:8080/lams/servlet/authoring/storeLearningDesignDetails
In the File To Post field, put in the path of a file that contains the wddx packet to be submitted. Only the wddx packet may be in the file, and the packet should start at position 1 in the file - there is some simple validation that checks that it is a wddx packet before proceeding.
When you click "Send", it should display the response packet that would normally be sent to Flash. If you get a 500 error then check the logs - an exception has usually been thrown.
If you want to void a structured version of the packet, with all the WDDX stuff removed, then run the ReportWddxStructureServlet. In the action field Form Action field enter "http://localhost:8080/lams/servlet/dumpWDDX" and select a file containing a packet. This will deserialise the WDDX packet and dump the contents into a file in the server's LAMS dump area. The name of the file will be displayed on the screen. Normally this would only be run on a local PC - if it is on a server you will have to log onto the server and download the file.