##### General Information

- Overview
- Features
- Specification
- Getting Started
- Howto Build Turbine
- Changes

##### Documentation

- Services
  - Assembler Broker Service
  - Avalon Component Service
  - Crypto Service
  - Cache Service
  - Component Service
  - Factory Service
  - Intake Service
  - JSON-RPC Service
  - JSP Service
  - Localization Service
  - MimeType Service
  - Naming Service
  - Parser Service
  - Pool Service
  - Pull Service
  - RunData Service
  - Scheduler Service
  - Security Service
  - Servlet Service
  - Session Service
  - Template Service
  - Torque Security Service
  - Torque Security Service Schema
  - UI Service
  - Unique ID Service
  - Upload Service
  - Velocity Service
  - XML-RPC Service
  - XSLT Service
- Howtos
- Wiki
- JavaDocs

##### Development

- Proposals
- How To Help
- Todo

##### Project Documentation

- Project Information
- Project Reports

##### Apache

- Apache Website
- License
- How the ASF works
- Sponsorship
- Thanks
- Security

## 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
    {
        public String getHello(String clientParameter)
        {
            return "Hello " + clientParameter;
        }
        public 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
        {
            MyJsonFunctions myFunctions = new MyJsonFunctions();

            // 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\jsonrpc` 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.