Displaying items by tag: documentation
Monday, 26 July 2010 20:13
Most of the time, you won’t touching the server unless you wanted to do some major customization. The server simply forward the message and control the heartbeat connection of each client.
Open up the /Server/Function.php. The functions which declared as public are able to be called by the client. To define your own server function, just add it like this:
The first parameter must be the client’s message object. Please refer to the API for details about what you can do with the Jsrs_Server_Message_Client object.
The second parameter will be the client’s connection object. This object hold the connection resources that allowed you to send message back to the client.
The last parameter is the function’s parameters passed by the client. It is optional. The parameter is an associative array. If the client did not specify the key of the value, the index of the array will be numeric in ascending order starting from 0. Eg: $params, $params, ....
Customizing server function required extensive knowledge on how JsRS works. It is better for you to familar with the whole framework before doing the customization.
Below is the list of functions available from the server. Please note that the parameters is the required parameter from the client.
Monday, 26 July 2010 20:00
The proxy file will place within your application so that it can access your session data to determine the client’s ID. At current stage, the proxy only supports PHP application.
By default, there a file called proxy.php which already extended the proxy class (Jsrs_Proxy_Abstract) with the class name, “Standard”. The only function you need to override is the “_getClient” function.
You can determine by using your session data:
The function is accessing the session data and determines the user’s type. Of course, this might different depends on your application. The function must return either the full class name or the client object itself. The client object must be child class from Jsrs_Proxy_Client_Abstract. Read on the next section on defining user’s type.
You can override the default property that defined in the Jsrs_Proxy_Abstract class too:
If your JsRS server was hosted in another server, you might want to replace it with the IP address or the host name. You can change the listening port number if your server is listening at different port number. The $_defaultPermissive is to determine whether a message should be rejecting if the permission function was not defined (eg: sfPlus, cfSayHello). If you set to “denied”, means any server or client remote function that without defining the permission control function, will be rejected. By default, this value is “allowed”.
You might need to define the types of user that connected to your live application. By defining the user’s type, you can set the permission of each function for each type of user. By default, the “Standard” user class was defined for you. You must define at least 1 user type in order to run JsRS. For instance you wished to define a member user type:
You should save this class file as Member.php under /proxy/client/. This proxy will prevent the Member type of user to call a remote function name “redirect”. Note the prefix in front of the function. “cf” is refer to client function, while “sf” is refer to server function. The users with Member type are NOT able to call the server function “plus” too. Any non-false value returned will allowed the message being pass through the proxy and send to the server. Throwing an exception will caused the message being reject:
Throwing the proxy exception (Jsrs_Proxy_Exception) will invoke the exception handler in the client (exceptionHandler). You can throw any other exception object such as RuntimeException or Exception, these exceptional objects will NOT invoke the exceptionHandler function in the client script.
Note: For those functions that did not defined in your client class, by default, the message will be received or sent through. You can change this behavior by overriding the default value of $_defaultPermissive to “denied” in the Jsrs_Proxy_Abstract class.
The Helper class is to reduce the needs of extending your client class in order to perform some custom functionality. Most of the time, you might focus on the client class file (Jsrs_Proxy_Client_Class). For some client remote function, you might want to check the permission based on the MySQL database. Building the database connection on each client class is very troublesome neither extending your client class is a good idea too. What the Helper class can offer you is to allow you to define a class that access to the MySQL database and call it from your client class like this:
You can use this helper “IsAdmin” on any client class with the same statement. Please be careful with the helper name, the first character must be capital letter and the name must be exactly same as the Helper class file.
The $_helper object is defined in the Jsrs_Proxy_Client_Abstract. You don’t have to worry about it. Just call it directly to get your result.
By default, there is one helper class, “ServerBroker”. You can use this to invoke any server’s function without connecting to the server. The result returned is in array format. To call the function, you need at least one parameter which is the server’s function name. The second parameter has to be an array which represents your parameter. The parameter array can be an associative array. Example:
To make a server function call, do this:
The $result will return you an associative array with this value:
Notice on how the parameter being passed. You have to put all the value in the array and pass the array in the second parameter of the Helper class.
You must place your Helper class under /Proxy/Helper and your Helper class must inherit from Jsrs_Proxy_Helper_Abstract. You have to override the “run” method in order to perform your custom task. The “run” function is the default function when calling a Helper class:
For instance you want to define a MySQL database accessing Helper, you created a Helper class file named Jsrs_Proxy_Helper_IsAdmin.php in /Proxy/Helper:
You can always extends your Helper class. For example you have few Helper class that needs to access to MySQL database, you can create a MySQL Helper class that will automatically connect to the database once the Helper class was called. Then you will extends those Helper that needs to access the database from this parent class.
Sunday, 25 July 2010 23:28
Now you need to instantiate a socket object from the JsRS library. You can put this code right after the opening <body> tag or you can wrap it up within a function and call it later (onclick from a button).
The codes above will instantiate the socket object and initialize it with the proxy path, the event handler and the remote function or the common function.
Before you calling a remote function, you must define it. You can define the remote function either during the initialization or runtime:
Both are having the same result. Once you have defined the remote function, you can call it using the client remote calling function, "callCF".
Note: The first parameter is always the client’s (sender) object. The basic element is "id". You may get more info of the client through the "info" property. Eg: client["info"].
Calling a remote function is very simple. You have to specify the recipient’s ID and the function name.
The third and fourth parameters are optional. You must provide array for the first parameter even though there is only one recipient. Example:
Same goes to the function’s parameters, the third one. You must provide array even though it is only one parameter for the function. The acceptable parameter types are object, string, number and array.
The code above will call the remote client with the ID: 12 to invoke the remote function "sayHello" and passed the string "Hi there!" to the second parameter.
Under certain circumstances, you might want to retrieve information from the server. Please refer to the Server’s APIs for more details. It is very similar to calling a client remote function:
socket.callSF(funcName, [[params], callback]);
You have to specify the function’s name that you want to call on the server. Example:
The function "plus" is a test function from the server which take the parameters passed by you and do a summation. The returned result will be 80. If the message was successfully passed, you should received an alert message, "The result is 80".
Without the client’s ID, you can’t do any remote scripting. It is depend on what application you are writing and it will affect on how you store your client’s ID. I will explain how you going to get the client’s ID but I ain’t going to talk about how you store it.
In section b. ii., you know how to get the result from the server’s function. You can do the same thing for client. Meaning you send a remote function call to a specific client and ask the client to process and send back the data. For example you wanted to know the client’s name. You might need to define the remote function first:
The remote function above will prompt the user (using prompt function) and get the input as the result (user’s name) and then send back to the sender using the sendResult function.
If you are defining a remote function that required a callback, the last parameter is always a function for you to send back your result. Don’t get confused, lets read on first.
Now you’ve defined the remote function, it is time to call it:
The first and second parameters are the client’s ID and the remote function’s name respectively. Because the remote function do not required any parameter, so we skipped it. The third parameter will be your callback function.
The callback function will be invoked once the recipient processed and return back the result using "sendResult" function. The execution context within the callback function is the Jsrs instance. Meaning this.proxy will return you the proxy URL.
Event handlers allowed you to catch any events happened. Below is the list of event handlers:
Sunday, 25 July 2010 21:10
Download the latest version of JsRS from here. Once you’ve downloaded, unzip the archive to your local drive. Eg: C:\jsrs-1.0\
Note: Where the x.y is the version number. x is the major version while the y is the minor version number.
Alright, it's time to make the server alive! Launch your command-line interface. Depending on which platform you using, the steps are almost the same:
Note: For demo purposes, we want the server screen to be shown all the time so that we know what is happening. For production, please refer to the documentation on how to configure a production server.
It is depending on how you setting up your application. As long the proxy file are accessible within the domain (not cross domain, eg: www.domain1.com accessing proxy on www.domain2.com).
Now your directory will look like this:
You should see a form with buttons and textbox. With your server running, click on “Connect” button. You should see the message “Connected to server with the ID: <session ID>”. Congratulation, your socket server is working!
To have fun with the demo, open up another browser (must be different browser), go to the same URL, and click Connect.
Sunday, 25 July 2010 19:57
The requirements are pretty much similar to a web server. Just need some extra configuration on the existing server and some privileges on the server.
It was tested on Windows XP Professional SP3, Apache 2.2. (with PHP5.2), Firefox 3.5, Internet Explorer 8, Google Chrome 5.0.
Sunday, 25 July 2010 19:41
Sunday, 25 July 2010 19:31
JsRS is a light-weight scripting library framework that allowed you to build a live web application easily. You don’t have to create any database table for this framework. All you need to do is define what functions you wished to be call remotely and define the permission in the proxy file, and your application is ready to go!
While the diagram on the right is how JsRS works. The client will send a HTTP request to the server page which is the proxy. The proxy is a middleman between the client and the server. It will send the requested message to the server using specific port number (default is 38380). The HTTP request will be hold (wait) by the proxy until there is a new message coming from the server to this client. Once the proxy got a new message from the server, it will send it back to the client immediately.
socket.callCF(, "sendInstantMessage", ["Hi, my name is Kent."]);
The client’s ID is the ID that the client used to connect to the server. By default, the session ID will be used as the client’s ID.
Security might come into your concern when calling remote function. The Common Functions will store in a different context and is not stored in the global context. Meaning you don’t have to worry that other client are able to call the functions which is not part of the remote functions. For instance you have a function called “logout” which will destroy the user’s session and send the user back to the login page. Obviously you won’t put this as a remote function and causing the client being remote logout. Because the logout function was not defined in the remote function’s context, so this function will not be able to call remotely and your application is safe.
For more information, please read on the documentation.