JSON-RPC Service

The JSON-RPC Service supports JavaScript to Java AJAX communications using JSON-RPC-Java.

Configuration

# -------------------------------------------------------------------
#
#  S E R V I C E S
#
# -------------------------------------------------------------------
...
services.JsonRpcService.classname=org.apache.turbine.services.jsonrpc.TurbineJsonRpcService
...

Usage

There are a number of things you need to do in order to add AJAX functionality to your webapp. First you implement the functions: 

public class MyJsonFunctions
{
    private String getHello(String clientParameter)
    {
        return "Hello " + clientParameter;
    }
    private String getGoodbye(String clientParameter)
    {
        return "Goodbye " + clientParameter;
    }
}

Next you implement your Screen class to make your functions available: 

public class MyJsonScreen extends JSONScreen
{
    public void doOutput(RunData data) throws Exception
    {
        User user = data.getUser();

        MyJsonFunctions myFunctions = new MyJsonFunctions(user.getName());

        // Session specific
        TurbineJsonRpc.registerObject(data.getSession(), "myFunctions", myFunctions);

        // Global
        //TurbineJsonRpc.registerObjectGlobal("testGlobal", testObject);

        super.doOutput(data);
    }
}

Now we shift focus to your template classes. Firstly, there are a few useful utility functions that you need to make sure are available to the pages that will include AJAX functionality: 

// Body onload utility (supports multiple onload functions)
function SafeAddOnload(func) {
	var oldonload = window.onload;
	if (typeof window.onload != 'function') {
		window.onload = func;
	} else {
		window.onload = function() {
			oldonload();
			func();
		};
	}
}

// Prepare for possible JSON-RPC requests.
// jsonurl must be set before calling this function.
function jsonOnLoad() {
	try {
		jsonrpc = new JSONRpcClient(jsonurl);
	}
	catch(e) {
		if(e.message) {
			alert(e.message);
		}
		else {
			alert(e);
		}
	}
}

// Process a JSON-RPC request.
function jsonEval(evalStr) {
	try	{
		return eval(evalStr);
	}
	catch(e) {
		if(e.javaStack) {
			alert("Exception: \n\n" + e.javaStack);
		}
		else {
			alert("Exception: \n\n" + e);
		}
	}
	return null;
}

In these pages you also need to include the JavaScript necessary to process the JSON calls - this file is available as part of the JSON-RPC-Java distribution (it is included in the webapps\jaonrpc directory): 

$page.addScript($content.getURI('scripts/jsonrpc.js'))

Then you need to set up the specific handler for the page: 

<script type="text/javascript">
<!--
  ## Set up the JSON-RPC handler.
  var jsonurl = '$link.setScreen("MyJsonScreen")';
  SafeAddOnload(jsonOnLoad);
  ## myArg below would be provided when you call this function from your
  ## web page (usually you would retrieve something via the DOM or your
  ## favorite JavaScript DOM wrapper library).
  function retrieveHello(myArg) {
    ## This is a synchronous call.
    var helloResult = jsonEval("jsonrpc.myFunctions.getHello(" + myArg + ")");
    if(null == helloResult) {
      alert('Something went wrong!');
      return;
    }
    ## Here you would again use the DOM to include the result somewhere on your
    ## page.
  }
//-->
</script>

The above code is executable by users that are not logged into your application. Your Screen class can extend JSONSecureScreen to require that users be logged in before allowing execution.