.NET Invocation Guide for AJAX clients

.NET Invocation guide for AJAX clients	Search:
home / articles / NET invocation guide

INTRODUCTION


	WebORB and Rich Client System for AJAX clients support a variety of argument types and return values. This guide provides a set of instructions with live samples demonstrating AJAX invocations of .NET methods.

CLIENT SETUP

To enable client side binding to a .NET object, the Rich Client System library must be imported before any invocations take place:

The line of code shown above can be put in the <head> element of the page containing the script using the Rich Client System APIs. The location of the WebORB.js file on the web server is important. The code shown above imports the script from the same location where the page containing the code is loaded from. The "src" attribute can be modified to use an absolute path.

SERVER SETUP

The server side code must be deployed into a WebORB enabled ASP.NET application. Copy the assembly file into the /bin folder of the ASP.NET application and WebORB automatically exposes the classes from the assembly to the AJAX clients.

INVOCATION WALKTHROUGH

This guide reviews the following invocation scenarios:

Passing primitive argument to a server method
Passing multiple arguments to a server method
Passing date argument to a server method
Passing arrays
Passing complex types
Mapping client classes to server types
Invoking server methods with .NET collections as arguments
Storing data in server's session
Handling server-side exceptions on the client side

Passing primitive argument to a server method

The client invokes the echoInto method in the following class. The method takes a primitive integer argument.

C# code

namespace weborb.tests
{
public class PrimitiveTest
{
    public int echoInt( int intArg )
    {
      return intArg;
    }
}
}

The client side code uses the following script to invoke the .NET method synchronously or asynchronously:

JavaScript code

var proxy = webORB.bind( "weborb.tests.PrimitiveTest", "weborb.aspx" );
var syncResult = proxy.echoInt( 21 );

// to invoke asynchronously just add a Async object as the last argument
proxy.echoInt( 21, new Async( echoIntResponse ) );

function echoIntResponse( result )
{
}

Run the client example:

Method argument Sync Invoke Async Invoke Result:

AJAX Events:

Passing multiple arguments to a server method

The client invocation will take place on the following class:

C# code

namespace weborb.tests
{
public class MultipleArgsTest
{
    public Object[] echoStringBuilderDouble( System.Text.StringBuilder sb, Double d )
    {
      return new Object[] { sb, d };
    }
}
}

The client side code uses the following script to invoke the .NET method synchronously or asynchronously

JavaScript code

var proxy = webORB.bind( "weborb.tests.MultipleArgsTest", "weborb.aspx" );
var syncResult = proxy.echoStringBuilderDouble( "Hello World", 21 );

// to invoke asynchronously just add a Async object as the last argument
proxy.echoStringBuilderDouble( "Hello World", 21, new Async( echoMultipleArgResponse ) );

function echoMultipleArgResponse( result )
{
   // the result is an array
   // result[ 0 ] contains "Hello World"
   // result[ 1 ] contains 21
}

Run the client example:

Method arguments:
String argument
Number argument Sync Invoke Async Invoke Result:

AJAX Events:

Passing date argument to a server method

The client invokes the echoDate method in the following class:

C# code

namespace weborb.tests
{
public class PrimitiveTest
{
    public DateTime echoDate( DateTime date )
    {
      return date;
    }
}
}

The client side code uses the following script to invoke the .NET method synchronously or asynchronously

JavaScript code

var proxy = webORB.bind( "weborb.tests.PrimitiveTest", "weborb.aspx" );
var syncResult = proxy.echoDate( new Date() );

// to invoke asynchronously just add a Async object as the last argument
proxy.echoDate( new Date(), new Async( echoDateResponse ) );

function echoDateResponse( result )
{
// result object is the same date passed as an argument by the client
}

Run the client example:

Method argument (Date): Sync Invoke Async Invoke
Result:

AJAX Events:

Passing arrays to a server method

The client invokes the echoStringArray method in the following class:

C# code

namespace weborb.tests
{
public class StringsArrayTest
{
    public string[] echoStringArray( string[] stringarray )
    {
      return stringarray;
    }
}
}

The client side code uses the following script to invoke the .NET method synchronously or asynchronously:

JavaScript code

var proxy = webORB.bind( "weborb.tests.StringsArrayTest", "weborb.aspx" );
var arrayObj = new Array( "peaches", "organges", "apples" );
var syncResult = proxy.echoStringArray( arrayObj );

// to invoke asynchronously just add a Async object as the last argument
proxy.echoStringArray( arrayObj , new Async( echoStringArrayResponse ) );

function echoStringArrayResponse( result )
{
// result object is the same array passed as an argument by the client
}

Run the client example:

Method argument (array): array element 1: array element 2: array element 3:	Sync Invoke Async Invoke Result:
AJAX Events:

Passing JS objects as complex types to a server method

The client invokes the echoEmployee method in the following class:

C# code

namespace weborb.tests
{
public class ComplexTypesTest
{
    public Employee echoEmployee( Employee empl )
    {
      return empl;
    }
}

public class Employee
{
    private int employeeId;
    private string employeeName;
    private string employeeTitle;
    private string phoneNumber;
}
}

The client side code uses the following script to invoke the .NET method synchronously or asynchronously: The client code creates a JavaScript object with the same fields as the server side class. WebORB automatically adapts the data from the JS object to an instance of the Employee class.

JavaScript code

var proxy = webORB.bind( "weborb.tests.ComplexTypesTest", "weborb.aspx" );
var employeeObj = new Object();
employeeObj.employeeId = 515;
employeeObj.employeeName = "James Bond";
employeeObj.employeeTitle = "Vice President";
employeeObj.phoneNumber = "972.555.1212";

var syncResult = proxy.echoEmployee( employeeObj );

// to invoke asynchronously just add a Async object as the last argument
proxy.echoEmployee( employeeObj , new Async( echoEmployeeResponse ) );

function echoEmployeeResponse( result )
{
// result is a JS object with the same fields as the input argument
}

Run the client example:

Method argument (JS Object):		Sync Invoke Async Invoke Result:
Employee ID:
Employee Name:
Employee Title:
Phone Number:
AJAX Events:

Mapping client classes to server types. Using client class as a complex type argument.

In the previous example, the client side method argument is a plain JavaScript object. At times it is necessary to use client side classes instead of generic/anonymous JS objects in the method invocations. What may be even more important is to have the return value from the invocation to be converted to a certain type when the response becomes available. For example, in the example above, the return value is just an anonymous JavaScript object that has the same properties as the server-side class. The example below demonstrates how to map a server side type to a client side class.

The client invokes a method in the following class:

C# code

namespace weborb.tests
{
public class ComplexTypesTest
{
    public Employee echoEmployee( Employee empl )
    {
      return empl;
    }
}

public class Employee
{
    private int employeeId;
    private string employeeName;
    private string employeeTitle;
    private string phoneNumber;
}
}

The client side code uses the following script to invoke the .NET method synchronously or asynchronously. Notice the webORB.registerTypeFactory call. The API call registers a JavaScript function responsible for converting server side type to the client side class. In the example below, the createClientEmployeeClass function will be called by the Rich Client System, whenever server sends an instance of weborb.tests.Employee. The argument in the createClientEmployeeClass function is an anonymous JavaScript object representing the server side type. The object has the same properties as the server type.

JavaScript code

var proxy = webORB.bind( "weborb.tests.ComplexTypesTest", "weborb.aspx" );
webORB.registerTypeFactory( "weborb.tests.Employee", createClientEmployeeClass );

var employeeObj = new Employee();
employeeObj.employeeId = 515;
employeeObj.employeeName = "James Bond";
employeeObj.employeeTitle = "Vice President";
employeeObj.phoneNumber = "972.555.1212";

var syncResult = proxy.echoEmployee( employeeObj );

// to invoke asynchronously just add a Async object as the last argument
proxy.echoEmployee( employeeObj , new Async( echoEmployeeResponse ) );

function echoEmployeeResponse( result )
{
   // result is an Employee object
}

function createClientEmployeeClass( employeeObjInfo )
{
   var empl = new Employee();
   empl.setId( employeeObjInfo.employeeId );
   empl.setName( employeeObjInfo.employeeName );
   empl.setTitle( employeeObjInfo.employeeTitle );
   empl.setPhoneNumber( employeeObjInfo.phoneNumber );
   return empl;
}

Run the client example:

Method argument (Employee Object):		Sync Invoke Async Invoke Result:
Employee ID:
Employee Name:
Employee Title:
Phone Number:
AJAX Events:

Invoking server methods with .NET collections as arguments

The client invokes the echoHashtable method in the following class:

C# code

namespace weborb.tests
{
public class CollectionsTest
{
    public System.Collections.Hashtable echoHashtable( System.Collections.Hashtable map )
    {
      return map;
    }
}
}

The client side code uses the following script to invoke the .NET method synchronously or asynchronously:

JavaScript code

var proxy = webORB.bind( "weborb.tests.CollectionsTest", "weborb.aspx" );
var capitalsMapObj = new Object();
capitalsMapObj[ "USA" ] = "Washington, DC";
capitalsMapObj[ "Great Britain" ] = "London";
capitalsMapObj[ "Russia" ] = "Moscow";

var syncResult = proxy.echoHashtable( capitalsMapObj );

// to invoke asynchronously just add a Async object as the last argument
proxy.echoHashtable( capitalsMapObj, new Async( echoHashtableResponse ) );

function echoHashtableResponse( result )
{
   // result is an associative array - a data structure closest to hashtable
   // used on the server side. Since the server echoes the argument back, the object
   // is the same as on the imput side.
}

Run the client example:

Method argument ( hashmap ):

Sync Invoke Async Invoke

Result:

key 1:	value 1:
key 2:	value 2:
key 3:	value 3:

AJAX Events:

Storing data in server's session

The client uses the methods in the following class to store and retrieve data from the server. Per client's request WebORB creates an instance of the SessionData class using the 'session' activation. As a result, the object and hence the data stored in the object's field variables stays in the session associated with the client. The client/server session is maintained by a cookie.

C# code

namespace weborb.tests
{
public class SessionData
{
    // class stores data in a local private field variable
    private String data;

    // method to store data
    public void setData( String data )
    {
      this.data = data;
    }

    // method to retrieve data
    public String getData()
    {
      return this.data;
    }
}
}

The client side code uses the following script to store and retrieve data from the server-side. Notice the query parameter in the WebORB URL in the webORB.bind call. The "?activate=session" requests that an instance of weborb.tests.SessionData to be created and stored in the session associated with the client.

JavaScript code

var proxy = webORB.bind( "weborb.tests.SessionData", "weborb.aspx?activate=session" );

// store data on the server
proxy.setData( "hello world!" );

// retrieve data from the server
var syncResult = proxy.getData();

// syncResult now contains "hello world!"

// do the same thing asynchronously
proxy.setData( "hello world", new Async( dataStored ) );

function dataStored()
{
// retrieve data
proxy.getData( new Async( dataRetrieved ) );
}

function dataRetrieved( result )
{
// result now contains "hello world!"
}

Run the client example:

string to store in session:	Store data (sync call) Store data (async call)
string retrieved from session	Retrieve data (sync call) Retrieve data (async call)

AJAX Events:

Handling server side exceptions in the client code

The client invokes a method in the following class. When the y argument is 0, the code throws a 'division by zero' exception.

C# code

namespace weborb.tests
{
public class ExceptionsTest
{
    public float divide( int x, int y )
    {
      // division by zero will cause an exception
      return x / y;
    }
}
}

The client side code uses the following script to store and retrieve data from the server-side. The client catches the server error using either try/catch block for the synchronous invocations or a callback function for the asynchronous invocations.

JavaScript code

Run the client example:

Method arguments		Sync Invoke Async Invoke
argument X		Result:
argument Y		Result:

AJAX Events:



Copyright © 2003-2005 Midnight Coders, LLC.	Privacy Policy \| Contact Webmaster Home \| Products \| Customers \| Download \| Licensing \| Forum \| Developers \| About