Create project
- Select File -> New -> Web -> Dynamic Web Project (any Java-project will do
if you are not using the JEE edition)
- Name the project "RepositoryServiceWeb"
- Right click on your project and select "Add SMODL Nature"
- Select the "src" folder of your project (under "Java Resources") and right click; select New -> File
- Name this file "service.smodl"
- Copy and paste the following SMODL markup into
"service.smodl" and save it (Use "Source" tab in default Eclipse XML
editor)
The SMODL file can also be fetched from the online service by appending "?smodl" to the URL: http://examples.smodl.org/ajax-tutorial/service/JSON?smodl
The generated code is a so-called proxy object built on top of the MooTools Request object which again is a wrapper around XMLHttpRequest. The proxy allows you to invoke methods declared in the SMODL file, hiding all the networking. It triggers events when the invoked methods completes, both for successful and unsuccessful JSON responses.
- If you are not using
Eclipse for JEE Developers, create a folder called "WebContent" at the
root of your project
- Right-click on your SMODL file and choose "Properties"
- Select the MooTools pane
- Check the "Generate MooTools client" and specify project, path and name for the generated code as shown in picture above
- Click "OK" to save your settings and generate the proxy. Keep in mind that proxy is re-generated
every time you change the smodl-file.
We now create a HTML file which uses the generated proxy and implements a simple client to the online service. The proxy object is initiated with the service URL and options (optional).
- Right click your project and select New -> Other -> Web -> HTML file (or just a plain file if you're not using the JEE edition)
- Create a new file called index.html in the WebContent
directory and paste the following html into it
The interesting part of this code is at the end of the
script-tag where we register event. The event "domready" is called when
the DOM has successfully
been loaded. When this event is triggered, it proceeds to register
events so that our client is notified when responses to method-calls
are received. See next section for details...
-
Calling methods
The generated code is a proxy object which abstracts away unnecessary implementation details. This object contains the JSON-RPC calls that is generated from the SMODL file and implements events for each of the methods. It provides events for successful JSON responses as well as unsuccessful, more about this in next section.
Calling a method on the proxy object is very simple. Just use the method name and parameters as specified in the SMODL file.
service.loginUser("user", "pass");
In order for this to make sense in an AJAX context, we need to register an event and specify what happens when the function returns:
-
Registering events
MooTools is event based which means that we register and listen to events instead of specifying callbacks for each method-call. The generated proxy uses a simple naming convention where the name of the method defines the name of the event.
Example:
service.addEvent('getCurrentUsername', function(res) {
alert(res.result);
});In this example we register an event called getCurrentUsername, and specify what function that should be executed upon a fired event. When successful, this function alerts the result to the user.
More about MooTools and events can be found here.
-
Handling errors
There are some predefined events in MooTools such as failure and timeout, which signal errors. However, these deal with the transfer of a request, not the request itself, i.e. they are fired only if the transfer itself failed. If an error occurs on the server side (e.g. the method in the service failed) the transfer is considered successful and a ''success'' event if fired. In this case ''failure'' is not fired but request contains a fault code and message. In order to handle such errors differently you can register an error handler for an error associated with a method. As with the regular events we use a simple naming convention for failure-events: <methodname>Failure.
service.addEvent('loginUserFailure', function(res) {
alert('Error ' + res.error.faultCode + " " + res.error.faultString);
});In this example we alert the user with the fault code and message when a loginUser call fails.
The following is an example of events generated for this tutorial's SMODL file:
Success event Failure event loginUser loginUserFailure logoffUser logoffUserFailure getCurrentUsername getCurrentUsernameFailure
Cross Origin Resource Sharing and MooTools
Browsers today enforce the so-called Same Origin Policy which prevents scripts from accessing resources loaded from a different domain. This makes sense in general for security-reasons, but in our case it means that our HTML file would have to be served by the same server running the service. Cross-Origin Resource Sharing (CORS) is a W3C working draft which aims to enable client-side cross-origin requests to deal safely with situations like ours.
Smodl Development Suite supports the server-part of CORS but the current version of MooTools do not support the client-part of CORS according to the standard. Hence Smodl Development Suite applies a small workaround to deal with this.
Of the major browser vendors, Opera is (at the time of writing)
still not supporting CORS. As of version 8, Internet Explorer partially
supports CORS through the XDomainRequest object but unfortunately this
isn't (at the time of writing) supported by MooTools. More details
about SMODL and CORS can be found here
- please refer to MooTools documentation for updates on browsers and
features supported by MooTool. However, the simplest way to test this
is to use Firefox or Chrome.
In order to test our MooTools-client we must load the file "index.html" into our browser. The natural way would be to load it as a local file, but this does not work in most browsers due to restrictions concerning CORS (the exception is recent versions of Firefox - see details in table linked above). Hence, we decide to serve it from a http-server...
Using the SMODL standalone server
The by far quickest and simplest way to serve your html-file is to use the in-built standalone server in Smodl Development Suite .
- Right click your "WebContent" directory and select "Run As/Serve static files in directory"
- Leave default settings in the dialog which appears and press the "Run" button
- Your webpage can now be found on http://localhost:9080/index.html
Note that the in-built server by default allows access only from
localhost. In order to let other computers load your client, add "-a"
to the "Program Arguments" in the "Arguments"-tab.
Using Tomcat to serve your client
If you plan to create lots of html-files and experiment with
other services, you can set up Tomcat and have it serve your
web-application. (This option requires an Eclipse-installation with JEE support.)
-
In the Java EE perspective, select the "Server" tab and create a new server.
-
Choose Apache Tomcat
-
Add correct project
-
Start the Tomcat server
- You should now be able to load your client at http://localhost:8080/RepositoryServiceWeb/
When pressing "Next", you need to specify where your Tomcat
installation is located.
